标准化 MD 文件体系
AI 编程的第一步不是写提示词，而是让项目拥有稳定的 Markdown 上下文。Claude Code、Codex、IDE 插件和团队成员都需要从这些文件里知道：项目是什么、怎么运行、什么算完成、哪些事情不能做。
文件清单
| 文件 | 主要读者 | 用途 |
|---|---|---|
README.md | 所有人 | 项目是什么、如何启动、主要目录 |
AGENTS.md | Codex 和通用 agent | 项目规则、命令、约束、完成标准 |
CLAUDE.md | Claude Code | Claude 项目记忆、工作方式、常用约束 |
docs/project/requirements.md | PM、开发、AI | 需求、用户故事、范围 |
docs/project/acceptance.md | PM、测试、AI | 验收标准和手动验收步骤 |
docs/project/design-context.md | 设计、前端、AI | 视觉、交互、组件和设计约束 |
docs/project/test-strategy.md | 开发、测试、AI | 测试范围、命令、质量门禁 |
docs/project/risk-register.md | PM、负责人、AI | 风险、影响、缓解措施 |
docs/project/release-checklist.md | PM、开发、运维 | 发布前检查和回滚 |
README.md
用途：给新人、PM、AI 工具建立项目第一印象。
来源：课堂推荐直接从所选 Markdown 资料包解压得到，例如 codex-md-kit-zh.zip 或 claude-md-kit-zh.zip。如果不用资料包，才按下面模板自己创建。
模板：
markdown
# AI 项目交付看板
AI 项目交付看板，用于演示 Claude Code 和 Codex 从需求到交付的完整流程。
## 本地启动
- 安装依赖：npm install
- 开发预览：npm run dev
- 构建：npm run build
## 主要目录
- src/：应用源码
- docs/project/：需求、验收、风险和发布文档
- tests/：测试
## 完成标准
- 页面能本地运行
- 核心交互符合 docs/project/acceptance.md
- 构建命令通过AGENTS.md
用途：给 Codex 和其他 agent 明确项目工作协议。
模板：
markdown
# AGENTS.md
## 项目概览
这是一个用于 AI 交付看板演示的小型 Web 应用。
## 常用命令
- 安装依赖：npm install
- 开发预览：npm run dev
- 构建：npm run build
- 测试：npm test
## 工作规则
- 实现前先阅读 docs/project/requirements.md 和 docs/project/acceptance.md。
- 第一版不添加数据库。
- 保持改动小而可审查。
- 修改 UI 行为后，运行构建并记录手动检查结果。
## 完成标准
- 构建通过。
- 验收清单已满足。
- 最终回复列出修改文件、验证结果和已知风险。依据：
CLAUDE.md
用途：给 Claude Code 项目记忆和工作习惯。
模板：
markdown
# CLAUDE.md
## 项目上下文
本项目用于演示在培训中构建 AI 交付看板。
## Claude Code 规则
- 开始前先阅读 README.md 和 docs/project/*.md。
- 编辑前先复述目标并提出简短计划。
- 优先保持小提交和可见验证。
- 添加依赖前先说明原因并确认。
## 产品规则
- 第一版不做登录、不做数据库、不做实时协作。
- 看板必须支持状态筛选和空状态。依据：
docs/project/requirements.md
模板：
markdown
# 需求说明
## 目标
为项目经理和开发构建一个 AI 交付看板。
## 用户故事
### 按状态筛选任务
作为项目经理，我希望按任务状态筛选，以便快速看到阻塞项。
## 不做范围
- 用户登录
- 数据库存储
- 实时协作docs/project/acceptance.md
模板：
markdown
# 验收标准
## 任务列表
- 显示任务标题、负责人、状态、优先级和截止日期。
- 当没有任务匹配筛选条件时，显示空状态。
## 状态筛选
- 支持待处理、进行中、评审中、已完成。
- 切换筛选条件时页面不重新加载。docs/project/design-context.md
模板：
markdown
# 设计上下文
## 受众
日常使用看板的项目经理和开发。
## UI 方向
- 信息密度适中但易读的工作型看板。
- 不做营销式首屏。
- 使用状态标签和紧凑卡片。
## 状态
- 加载中
- 空状态
- 筛选后无结果
- 错误状态docs/project/test-strategy.md
模板：
markdown
# 测试策略
## 自动化检查
- npm run build
- npm test
## 手动检查
- 状态筛选可用。
- 空状态可用。
- 任务详情可读。docs/project/risk-register.md
模板：
markdown
# 风险清单
| 风险 | 影响 | 缓解方式 | 负责人 |
| --- | --- | --- | --- |
| AI 添加不必要的后端 | 范围膨胀 | AGENTS.md 明确 v1 不使用数据库 | 技术负责人 |
| PM 需求描述模糊 | 返工 | 编码前先写 acceptance.md | PM |docs/project/release-checklist.md
模板：
markdown
# 发布检查清单
- [ ] 构建通过
- [ ] 已检查验收标准
- [ ] 未提交密钥
- [ ] 已记录已知风险
- [ ] 已写明回滚方案维护原则
- 短文件优先，超过一个主题就拆分。
- 每个文件都有明确读者。
- 需求变化先改 MD，再让 AI 改代码。
- AI 做完后，把新约定和风险补回 MD。