Files

T

chengmaandClaude Opus 4.8 ef288b0021 docs: add one-task-per-file convention for multi-agent concurrency

多个 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>

2026-07-08 15:00:07 +08:00

5.0 KiB

Raw Blame History

Harness Coding 文档样本库

本仓库用于沉淀一个新项目交给 AI coding agent 开发前，建议准备的文档集合。

这些文档参考了 D:\opc_project\lingo\docs 的实际项目文档结构，抽象为可复用模板：从项目入口、愿景、需求、技术栈、架构、编码规则，到任务看板、执行进度、API、路由和当前状态。

推荐文档集合

文档	作用
`AGENTS.md`	Codex / 通用 AI coding agent 的仓库级入口
`CLAUDE.md`	Claude Code 的仓库级薄入口
`tasks.md`	本样本库自身的维护任务列表
`init.sh`	标准启动与验证入口脚本（Unix shell / WSL / Git Bash），统一安装 + 验证 + 打印启动命令
`init.ps1`	标准启动与验证入口脚本（Windows 原生 PowerShell），与 `init.sh` 等价，按操作系统二选一
`progress.md`	复制到新项目后的执行历史流水，记录任务执行、验证、阻塞和决策
`docs/README.md`	文档导航，总览所有项目文档
`docs/00-ai-start-here.md`	AI coding agent 的入口、阅读顺序、任务领取规则
`docs/01-vision.md`	项目为什么做、为谁做、什么不做
`docs/02-requirements.md`	产品需求、用户故事、验收标准
`docs/03-tech-stack.md`	技术选型和运行命令
`docs/04-architecture.md`	系统结构、职责边界、数据模型、开发顺序
`docs/05-coding-rules.md`	AI 写代码前必须遵守的硬规则
`docs/06-tasks.md`	可逐步交付的任务看板（单 agent / 小项目）
`docs/tasks/README.md`	一任务一文件约定：多 agent 并发时避免抢改同一看板/进度文件
`docs/adoption-checklist.md`	已有项目接入 harness 文档的迁移清单
`docs/api.md`	API 合约模板
`docs/routes.md`	页面路由、组件归属、导航规则
`docs/clean-state-checklist.md`	会话收尾检查清单，保证下一轮无需人工修复即可开工
`docs/current-state.md`	当前实现状态快照，防止计划和代码现实脱节
`docs/method-map.md`	失败模式 → 首要修复 → 工件的诊断 / 导航对照表
`docs/evaluator-rubric.md`	单次会话输出的结构化评审评分表
`docs/quality-document.md`	代码库长期健康度追踪（产品域 × 架构层评级）

使用方式

最小必选集

只想先让 agent 稳定工作时，先复制这些文件：

AGENTS.md
CLAUDE.md
docs/00-ai-start-here.md
docs/05-coding-rules.md
docs/06-tasks.md
docs/current-state.md
progress.md
init.sh 或 init.ps1

完整推荐集

新项目从零开始时，建议复制根目录入口文件、docs/ 目录、progress.md，并按操作系统选择 init.sh 或 init.ps1。复制后按顺序处理：

从 docs/01-vision.md 和 docs/02-requirements.md 开始替换业务内容。
在 docs/03-tech-stack.md 固定技术选型，不确定的选项标为待定。
在 docs/04-architecture.md 写清事实来源、数据模型、系统边界。
在 docs/06-tasks.md 拆出小任务，要求 AI 每轮只领取一个任务。
替换 init.sh 或 init.ps1 顶部三个命令，并把真实命令同步到 docs/03-tech-stack.md、docs/00-ai-start-here.md 和 docs/current-state.md。
用 progress.md 追加记录每轮执行历史，用 docs/current-state.md 覆盖更新当前快照。
开始编码前，让 agent 先读 docs/00-ai-start-here.md。

已有项目接入

已有代码仓库不要急着让 agent 做新功能。先按 docs/adoption-checklist.md 建立当前状态、启动路径、验证路径和任务看板；第一轮任务优先修复基线，而不是扩大功能范围。

可选增强集

项目进入多轮长期开发后，再按需启用：

docs/clean-state-checklist.md：每轮结束前检查仓库是否可恢复。
docs/method-map.md：遇到失败模式时定位该补哪个工件。
docs/evaluator-rubric.md：评审单次 agent 输出质量。
docs/quality-document.md：追踪代码库长期健康度。

tasks.md 是本样本库自身的维护任务；复制到新项目后，项目任务默认写在 docs/06-tasks.md。如果新项目希望把任务看板放在根目录，可把 docs/06-tasks.md 复制或改名为根目录 tasks.md，并同步更新 docs/README.md、docs/00-ai-start-here.md 和 docs/current-state.md 中的链接。

核心原则：文档不是给人看的装饰，而是给 agent 执行时用的约束、事实来源和验收标准。

5.0 KiB Raw Blame History