chengmaandClaude Opus 4.8
ef288b0021
多个 agent 并发时抢改单一看板/进度文件会导致读到旧版本、ID 撞号、合并冲突。 新增 docs/tasks/（README 约定 + _template）：一任务一文件、frontmatter、防撞号、 执行记录写进任务文件、不逐任务改共享收尾文件。method-map 增对应失败模式行； 06-tasks/00-ai-start-here 加多 agent 分支；README/docs/README 登记；tasks.md 记 H-407。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
项目文档导航
复制到新项目后，先替换本文中的项目名称和一句话定位，再逐个补齐后续文档。
一句话定位
【项目名】是一个【目标用户】使用的【产品类型 / 系统类型】，用于解决【核心问题】，第一版先完成【MVP 闭环】。
示例：
这是一个面向小团队的工单协作系统，第一版先跑通「提交工单 -> 分派 -> 处理 -> 关闭」闭环。
文档导航
../AGENTS.md：Codex / 通用 AI coding agent 的仓库级入口。../CLAUDE.md：Claude Code 的薄入口，具体规则以AGENTS.md为准。../tasks.md：当前样本库自身的维护任务列表，不是复制到新项目后的业务任务看板。../progress.md：复制到新项目后的执行历史流水，只追加记录任务执行、验证、阻塞和决策。- AI 开发入口：agent 每次开始工作的入口、阅读顺序和任务领取规则。
- 项目愿景：为什么做、为谁做、产品原则、非目标。
- 需求：要什么、用户故事、验收标准，不写技术实现。
- 技术栈：确定使用哪些框架、库、数据库、部署方式。
- 架构设计：系统结构、模块职责、数据模型、关键风险和开发顺序。
- 编码规则：AI 写代码前必须遵守的硬约束。
- 任务看板：按依赖拆分的小任务，agent 每轮只做一个（单 agent / 小项目）。
- 任务文件（多 agent 并发）：一任务一文件
docs/tasks/T-<编号>.md，多 agent 并发时避免抢改同一看板/进度文件。 - 已有项目接入清单：把本模板补进已有代码库时的迁移步骤和第一轮任务建议。
- API 合约：前后端接口形状、错误格式、鉴权约定。
- 路由与页面结构：页面路由、页面职责、组件归属。
- 当前实现状态：可覆盖的当前快照，记录仓库现实状态、可运行命令和下一步可做任务。
- 收尾检查清单：会话结束前逐项检查，保证下一轮无需人工修复即可继续。
- 方法对照表：失败模式 → 首要修复 → 工件；出问题先查这里对症补工件。
- 评审评分表：单次会话输出的结构化评审（6 维 0-2 分 + 校准说明）。
- 质量文档：代码库长期健康度追踪，区别于单次输出评审。
../init.sh/../init.ps1：标准启动与验证入口脚本（根目录），统一安装、验证和启动命令。按操作系统二选一：WSL / Git Bash / macOS / Linux 用init.sh，Windows 原生 PowerShell 用init.ps1；换技术栈只改脚本顶部三个命令变量；未替换前脚本会主动失败，避免把示例命令误当真实项目命令。
任务 / 进度 / 当前状态
06-tasks.md维护任务看板：任务 ID、依赖、验收要点和状态。../progress.md维护执行进度：每轮实际做了什么、跑了什么验证、遇到什么阻塞、做了什么决策。current-state.md维护当前快照：当前目录、当前可运行命令、已完成任务摘要和下一个可领取任务。
如果新项目希望任务看板放在根目录，可把 06-tasks.md 复制或改名为根目录 tasks.md，并同步更新本文、00-ai-start-here.md 和 current-state.md 的链接。已有项目接入时，先读 adoption-checklist.md，不要直接领取新功能。
维护原则
- 需求变化先改文档，再改代码。
- 代码现实变化后同步
current-state.md和06-tasks.md，执行过程追加到../progress.md。 - API、数据模型、路由、技术栈一旦在文档中定稿，代码不得另起一套。
- agent 开始新任务前，必须从
00-ai-start-here.md进入。