Customization Guide

定制化指南

如何将 ai-coding-ok 调整到适配你的项目需求。哪些可以改，哪些不能改，如何安全地改。

---

哪些可以定制

✅ 可以安全修改

文件	定制什么	时机
project-memory.md	项目事实、架构、约束、已知问题	事实变化时
decisions-log.md	为你的决策添加新 ADR	做出架构决策时
task-history.md	（AI 自动管理）	无需
coding-standards.md	语言特定规范、lint 规则、命名约定	初始设置时
workflows.md	添加项目特定的工作流场景	流程与默认不同时
system-prompt.md	Agent 角色、角色定义	很少——仅当项目文化显著不同

⚠️ 谨慎修改

文件	注意事项
AGENTS.md	保留顶部的 PDCA 强制要求块。下方架构部分可定制。
copilot-instructions.md	保留 PDCA 强制执行块和强制输出格式。下方添加项目特定规则。
CLAUDE.md	保留 STOP 指令和 @AGENTS.md 导入。

❌ 不要修改

文件	原因
SKILL.md（在 ai-coding-ok 仓库中）	这是框架源码——修改会影响所有项目
模板文件（templates/en/、templates/zh/）	这些是产品源码——在源头修改行为，不在已安装文件中
版本标记（<!-- ai-coding-ok: vX.Y -->）	升级系统依赖这些标记

---

定制 project-memory.md

这是最常被定制的文件。以下是如何保持其有用：

添加新约束

## ⚠️ 关键约束

1. 未经用户明确许可不得 git push
2. 所有 API 接口必须有输入校验
3. **所有金额计算必须使用 Decimal，禁止 float** ← 添加项目特定约束

添加已知问题

## 🐛 已知问题与常见坑

| # | 问题 | 解决方案 | 日期 |
|---|------|---------|------|
| 1 | SQLite 并发写入时锁定 | 使用 WAL 模式（见 ADR-006） | 2026-07-14 |

更新架构

添加新模块时更新架构部分：

## 📦 核心模块

| 模块 | 描述 | 状态 |
|------|------|------|
| api/products.py | 商品 CRUD + 搜索 | ✅ 完成 |
| api/orders.py | 订单管理 | 🔨 进行中 |
| services/payment.py | 支付网关集成 | 📋 计划中 |

清理过时内容

如果 project-memory.md 超过 500 行：

1. 将已永久解决的旧"已知问题"移到 docs/ 文件
2. 将废弃的架构决策以"已废弃"状态移到 decisions-log.md
3. 归档已删除功能的旧模块描述

---

定制 coding-standards.md

替换为你的语言规范

Python 项目：

## 代码风格
- 遵循 PEP 8
- 使用 `from __future__ import annotations`
- 所有公开函数加类型注解
- 文档字符串：Google 风格

JavaScript/TypeScript 项目：

## 代码风格
- 遵循 StandardJS
- Prettier 格式化
- ESLint 推荐规则
- 所有导出加 JSDoc

Go 项目：

## 代码风格
- 遵循 Effective Go
- `gofmt` + `goimports`
- 表格驱动测试
- 错误返回，库代码禁止 panic

---

定制 workflows.md

添加项目特定工作流

## 数据库迁移

1. 在 `migrations/` 中创建迁移文件
2. 测试正向和反向迁移
3. 对照生产数据副本运行
4. 如果 schema 文档变化，更新 `project-memory.md`
5. ⚠️ 更新 `task-history.md` 记录迁移摘要

---

为不同项目类型定制

Web 应用

# 在 project-memory.md 中
## 技术栈
- 前端：React 18 + TypeScript + TailwindCSS
- 后端：Python 3.12 + FastAPI
- 数据库：PostgreSQL 16
- 缓存：Redis
- 测试：Jest（前端）、pytest（后端）

CLI 工具

# 在 project-memory.md 中
## 技术栈
- 语言：Go 1.22
- CLI 框架：Cobra
- 配置：Viper
- 测试：标准库 + testify

---

定制化反模式

❌ 不要删除 PDCA 强制要求块

<!-- 错误：不要删除这个 -->
## ⚠️ AI Agent 必读规范（每次任务必须执行）

删除它等于废掉了 ai-coding-ok 的全部意义。

❌ 不要手动编辑模板占位符

<!-- 错误：不要让 {{占位符}} 残留或手动填充 -->
{{项目名称}}  ← 让 AI 在安装时填充

❌ 不要在记忆文件中放密钥

<!-- 错误：记忆文件会被提交到 git -->
API_KEY=sk-abc123  ← 永远不要在这里放密钥

使用环境变量或 .env 文件（gitignored）。

---

下一步

• 升级 ai-coding-ok — 升级如何保留你的定制
• 模板系统 — 理解模板架构
• 团队最佳实践 — 在团队中标准化定制