opc/harness_coding_docs
2
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

Update harness coding documentation templates

Browse Source
This commit is contained in:
QiuSW
2026-06-24 17:07:53 +08:00
parent d6c0e5b612
commit 2b4a842d7a
13 changed files with 189 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+4 -3
View File
@@ -10,9 +10,9 @@
## 文档位置
harness coding 需要的项目文档模板集中在 `docs/` 目录。
harness coding 需要的项目文档模板主要集中在 `docs/` 目录；根目录还包含 `progress.md` 执行流水模板。
后续 Codex 或其他 AI coding agent 进入使用这些模板的新项目时，应先读取仓库级规则文件，再从 `docs/00-ai-start-here.md` 开始建立上下文；该文件会继续导航到需求、技术栈、架构、编码规则、任务看板和当前状态。
后续 Codex 或其他 AI coding agent 进入使用这些模板的新项目时，应先读取仓库级规则文件，再从 `docs/00-ai-start-here.md` 开始建立上下文；该文件会继续导航到需求、技术栈、架构、编码规则、任务看板、执行流水和当前状态。
根目录 `README.md` 和 `docs/README.md` 主要用于人类快速了解样本库和文档清单；agent 真正开始编程时，以 `docs/00-ai-start-here.md` 作为工作入口。
@@ -24,7 +24,8 @@ harness coding 需要的项目文档模板集中在 `docs/` 目录。
2. `docs/README.md`：了解文档导航。
3. `docs/00-ai-start-here.md`：理解新项目中 agent 的入口流程。
4. `docs/05-coding-rules.md`：理解模板中的编码纪律。
5. 与当前任务相关的具体文档。
5. `progress.md`：理解执行流水和当前状态的职责边界。
6. 与当前任务相关的具体文档。
如果用户要求修改某类模板，优先阅读对应文件，不要只凭文件名猜内容。
CLAUDE.md
+6 -47
View File
@@ -1,52 +1,11 @@
# CLAUDE.md
> Claude Code 的仓库级上下文。进入本仓库后，先读本文，再读 `AGENTS.md` 和 `docs/00-ai-start-here.md`。
> Claude Code 的仓库级薄入口。进入本仓库后，先读本文，再读 [`AGENTS.md`](AGENTS.md)。
## 仓库用途
本仓库的权威 agent 规则、文档入口、工作边界和验证方式统一维护在 [`AGENTS.md`](AGENTS.md)。
这是 harness coding 文档样本库，目标是提供一套新项目启动前可复制的 AI coding 文档模板。
Claude Code 处理本仓库任务时：
这套模板参考了 `D:\opc_project\lingo\docs` 的真实项目文档结构，但本仓库产物应保持通用，不绑定 lingo 的业务、数据、技术栈或任务状态。
## 文档位置
harness coding 需要的项目文档模板集中在 `docs/` 目录。
后续 Claude Code 进入使用这些模板的新项目时，应先读取仓库级规则文件，再从 `docs/00-ai-start-here.md` 开始建立上下文；该文件会继续导航到需求、技术栈、架构、编码规则、任务看板和当前状态。
根目录 `README.md` 和 `docs/README.md` 主要用于人类快速了解样本库和文档清单；Claude Code 真正开始编程时，以 `docs/00-ai-start-here.md` 作为工作入口。
## 关键事实
- 根目录 `README.md` 是样本库总入口。
- `docs/README.md` 是模板文档导航。
- `docs/00-ai-start-here.md` 是新项目中 AI agent 的工作入口模板。
- `docs/05-coding-rules.md` 是新项目中 AI agent 的硬约束模板。
- `docs/06-tasks.md` 是任务看板模板，强调每轮只做一个任务。
- `docs/current-state.md` 用来记录代码现实，防止文档计划和实际状态脱节。
## Claude 工作方式
处理本仓库任务时：
1. 先确认用户是在要求修改模板本身，还是要求基于模板生成某个具体项目的文档。
2. 如果是修改模板，保持通用占位符和可复制性。
3. 如果是生成具体项目文档，允许替换占位符为该项目事实，但不要污染通用样本，除非用户明确要求覆盖模板。
4. 修改文件前先读相关模板，保持同一套命名和结构。
5. 修改后检查文档导航是否仍完整。
## 不要做
- 不要把真实密钥、token、账号、私有 URL 写入模板。
- 不要把旧项目的具体事实写成新项目通用规则。
- 不要把模板改成只适合某一种技术栈，除非用户明确要求。
- 不要在没有用户要求时创建应用代码、依赖配置或构建脚本。
## 常用检查命令
```powershell
Get-ChildItem -Recurse -File
rg -n "AGENTS.md|CLAUDE.md|00-ai-start-here|05-coding-rules|06-tasks" .
```
如果 `rg` 不可用，使用 PowerShell `Select-String`。
1. 先读取 [`AGENTS.md`](AGENTS.md)。
2. 再按 `AGENTS.md` 的要求进入 [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md) 和相关模板。
3. 不在本文重复维护任务流程、编码规则或文档清单，避免和 `AGENTS.md` 漂移。
README.md
+9 -5
View File
@@ -2,15 +2,16 @@
本仓库用于沉淀一个新项目交给 AI coding agent 开发前，建议准备的文档集合。
这些文档参考了 `D:\opc_project\lingo\docs` 的实际项目文档结构，抽象为可复用模板：从项目入口、愿景、需求、技术栈、架构、编码规则，到任务看板、API、路由和当前状态。
这些文档参考了 `D:\opc_project\lingo\docs` 的实际项目文档结构，抽象为可复用模板：从项目入口、愿景、需求、技术栈、架构、编码规则，到任务看板、执行进度、API、路由和当前状态。
## 推荐文档集合
| 文档 | 作用 |
| --- | --- |
| [`AGENTS.md`](AGENTS.md) | Codex / 通用 AI coding agent 的仓库级入口 |
| [`CLAUDE.md`](CLAUDE.md) | Claude Code 的仓库级上下文入口 |
| [`CLAUDE.md`](CLAUDE.md) | Claude Code 的仓库级薄入口 |
| [`tasks.md`](tasks.md) | 本样本库自身的维护任务列表 |
| [`progress.md`](progress.md) | 复制到新项目后的执行历史流水，记录任务执行、验证、阻塞和决策 |
| [`docs/README.md`](docs/README.md) | 文档导航，总览所有项目文档 |
| [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md) | AI coding agent 的入口、阅读顺序、任务领取规则 |
| [`docs/01-vision.md`](docs/01-vision.md) | 项目为什么做、为谁做、什么不做 |
@@ -21,15 +22,18 @@
| [`docs/06-tasks.md`](docs/06-tasks.md) | 可逐步交付的任务看板 |
| [`docs/api.md`](docs/api.md) | API 合约模板 |
| [`docs/routes.md`](docs/routes.md) | 页面路由、组件归属、导航规则 |
| [`docs/current-state.md`](docs/current-state.md) | 当前实现状态，防止计划和代码现实脱节 |
| [`docs/current-state.md`](docs/current-state.md) | 当前实现状态快照，防止计划和代码现实脱节 |
## 使用方式
1. 复制 `docs/` 到新项目。
1. 复制 `docs/`、`progress.md` 和需要的仓库级 agent 入口文件到新项目。
2. 从 `01-vision.md` 和 `02-requirements.md` 开始替换业务内容。
3. 在 `03-tech-stack.md` 固定技术选型，不确定的选项标为待定。
4. 在 `04-architecture.md` 写清事实来源、数据模型、系统边界。
5. 在 `06-tasks.md` 拆出小任务，要求 AI 每轮只领取一个任务。
6. 开始编码前，让 agent 先读 `00-ai-start-here.md`。
6. 用 `progress.md` 追加记录每轮执行历史，用 `current-state.md` 覆盖更新当前快照。
7. 开始编码前，让 agent 先读 `00-ai-start-here.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 执行时用的约束、事实来源和验收标准。
docs/00-ai-start-here.md
+8 -1
View File
@@ -18,7 +18,8 @@
4. [`04-architecture.md`](04-architecture.md)：系统结构、职责划分、数据模型和关键难点。
5. [`05-coding-rules.md`](05-coding-rules.md)：写代码前必须遵守的规则。
6. [`06-tasks.md`](06-tasks.md)：领取本轮唯一任务。
7. [`current-state.md`](current-state.md)：当前代码现实、可运行命令、下一步任务。
7. [`../progress.md`](../progress.md)：历史执行记录、验证结果、阻塞点和关键决策。
8. [`current-state.md`](current-state.md)：当前代码现实、可运行命令、下一步任务。
如果仓库根目录有 `AGENTS.md`、`CLAUDE.md` 或其他 agent 规则文件，也必须先读。仓库级规则优先于项目局部建议。
@@ -42,6 +43,7 @@
- 开始前把该任务状态改为 `DOING`。
- 本轮只完成这一个任务。
- 验收通过后把状态改为 `DONE`。
- 完成后把执行记录追加到 [`../progress.md`](../progress.md)，并覆盖更新 [`current-state.md`](current-state.md) 的当前快照。
- 做完即停，汇报验证结果，等待下一步指令。
如果代码实际状态和任务看板冲突，先说明冲突，不要擅自跳步或重排。
@@ -89,6 +91,11 @@ MVP 不做：
- 先看 `api.md` 的接口合约。
- 再看 `04-architecture.md` 的数据模型和鉴权边界。
做本地工具 / CLI / 无后端项目：
- 先看 `api.md` 中的本地模块合约、CLI 参数或事件合约。
- 再看 `04-architecture.md` 的本地模块边界和数据流。
做数据模型：
- 先看 `04-architecture.md` 的数据模型。
docs/02-requirements.md
+6
View File
@@ -63,4 +63,10 @@
- 【风险 1】：【为什么有风险，建议先如何验证】。
- 【风险 2】：【数据、性能、授权、依赖、体验等风险】。
- 【资金风险】：【是否涉及付款、退款、分账、对账，谁确认规则】。
- 【账号 / 权限风险】：【是否涉及用户账号、平台账号、代操作权限或凭证保存】。
- 【第三方平台风险】：【是否依赖平台规则、限流、封号、接口变更或人工审核】。
- 【自动化边界风险】：【是否会自动点击、批量提交、爬取、发送消息或触发不可逆操作】。
- 【隐私数据风险】：【是否处理个人信息、敏感文件、聊天记录、定位、联系方式等】。
- 【合规风险】：【版权、平台条款、行业监管、数据跨境、审计留痕等是否需要确认】。
- 【待确认问题】：【谁来决策，什么时候需要决策】。
docs/04-architecture.md
+16 -4
View File
@@ -5,14 +5,16 @@
## 一、系统结构
按真实产品形态替换下图。项目可以是 Web、桌面、CLI、本地自动化、移动端、插件或多端组合，不要强行保留不存在的后端层。
```text
用户
|
v
前端 / 客户端
前端 / 客户端 / CLI / 本地工具
|
v
后端 API
后端 API / 本地核心模块
|
v
数据库 / 文件 / 第三方服务
@@ -22,8 +24,9 @@
- 前端：【框架、入口目录】
- 后端：【框架、入口文件】
- 本地工具：【CLI 入口、桌面入口、自动化脚本入口】
- 数据库：【类型、迁移方式】
- 外部服务：【支付、邮件、对象存储、AI 服务等】
- 外部服务：【邮件、对象存储、AI 服务、第三方平台等】
## 二、职责划分
@@ -40,6 +43,13 @@
- 【数据校验】
- 【异步任务 / 文件处理】
如果项目没有后端，删除本节或改为 **本地核心模块**：
- 【模块入口和公开函数】
- 【输入输出合约】
- 【文件读写 / 系统调用 / 第三方平台调用边界】
- 【错误处理和重试策略】
**数据库 / 存储**
- 【持久化哪些数据】
@@ -112,10 +122,12 @@ project/
按实际技术栈替换：
- `src/`：【前端 / 客户端代码】
- `server/`：【后端代码】
- `server/`：【后端代码；无后端项目可删除或替换为核心模块目录】
- `scripts/`：【数据校验、迁移、构建辅助脚本】
- `tests/`：【测试目录】
路径只是模板占位，初始化后必须按真实技术栈和项目形态替换，不要保留误导性的空目录说明。
## 七、架构纪律
- 业务事实和 schema 变化必须同步更新本文。
docs/05-coding-rules.md
+10 -2
View File
@@ -37,7 +37,7 @@
- 技术栈以 `03-tech-stack.md` 为准。
- 新增依赖前先说明理由；未经确认不要引入重量级依赖。
- 模块职责以 `04-architecture.md` 为准，不跨层偷写逻辑。
- API 形状以 `api.md` 为准，页面路由以 `routes.md` 为准。
- API、本地模块、CLI 或事件合约以 `api.md` 为准，页面路由以 `routes.md` 为准。
## 5. 代码规范
@@ -74,6 +74,14 @@ go test ./...
- 绝不擅自删除用户已有文件或重置工作区。
- 绝不在没说明的情况下改公共接口、迁移数据结构或升级依赖。
## 8. 拿不准就问
## 8. 安全与合规
- 敏感信息只能使用占位符或环境变量名，不写真实账号、密钥、token、Cookie、私有 URL。
- 涉及第三方平台时，先在 `02-requirements.md` 或 `04-architecture.md` 写清平台规则、调用边界、限流和失败处理。
- 涉及资金、账号、权限、隐私数据或不可逆操作时，必须有显式验收标准和安全校验。
- 自动化脚本默认先支持 dry-run、日志和人工确认；批量提交、批量删除、批量发送等动作必须有边界和回滚说明。
- 不绕过平台限制、验证码、风控或权限校验。
## 9. 拿不准就问
问题要具体，说明你卡在哪里、有哪些选项、倾向哪个选项以及原因。
docs/06-tasks.md
+4 -1
View File
@@ -9,6 +9,9 @@
3. **不跳步**：依赖未完成的任务不能开工。
4. **完成定义**：以 [编码规则](05-coding-rules.md) 的验证清单为准。
5. **动手前**先读 `00-ai-start-here.md`、`05-coding-rules.md` 和 `current-state.md`。
6. **完成后**把任务状态同步到本文，把执行记录追加到 [`../progress.md`](../progress.md)，并覆盖更新 [`current-state.md`](current-state.md)。
如新项目希望任务看板放在根目录，可把本文复制或改名为根目录 `tasks.md`，并同步更新 `README.md`、`docs/README.md`、`00-ai-start-here.md` 和 `current-state.md` 的链接。
## 状态图例
@@ -20,7 +23,7 @@
| ID | 任务 | 依赖 | 验收要点 | 状态 |
| --- | --- | --- | --- | --- |
| T-001 | 初始化项目骨架 | - | 依赖安装成功；本地能启动；首页 / 入口可访问 | TODO |
| T-001 | 初始化项目骨架 | - | 依赖安装成功；本地能启动；首页 / 入口可访问；用真实可运行命令替换 `00-ai-start-here.md`、`03-tech-stack.md`、`05-coding-rules.md`、`current-state.md` 中的占位验证命令 | TODO |
| T-002 | 建立基础目录和配置 | T-001 | 目录结构符合 `04-architecture.md`；配置不含密钥 | TODO |
| T-003 | 加入最小测试 / 构建检查 | T-001 | 测试命令和构建命令可运行 | TODO |
docs/README.md
+12 -3
View File
@@ -13,8 +13,9 @@
## 文档导航
- [`../AGENTS.md`](../AGENTS.md)：Codex / 通用 AI coding agent 的仓库级入口。
- [`../CLAUDE.md`](../CLAUDE.md)：Claude Code 的仓库级上下文入口。
- [`../CLAUDE.md`](../CLAUDE.md)：Claude Code 的薄入口，具体规则以 `AGENTS.md` 为准。
- [`../tasks.md`](../tasks.md)：当前样本库自身的维护任务列表，不是复制到新项目后的业务任务看板。
- [`../progress.md`](../progress.md)：复制到新项目后的执行历史流水，只追加记录任务执行、验证、阻塞和决策。
- [AI 开发入口](00-ai-start-here.md)：agent 每次开始工作的入口、阅读顺序和任务领取规则。
- [项目愿景](01-vision.md)：为什么做、为谁做、产品原则、非目标。
- [需求](02-requirements.md)：要什么、用户故事、验收标准，不写技术实现。
@@ -24,11 +25,19 @@
- [任务看板](06-tasks.md)：按依赖拆分的小任务，agent 每轮只做一个。
- [API 合约](api.md)：前后端接口形状、错误格式、鉴权约定。
- [路由与页面结构](routes.md)：页面路由、页面职责、组件归属。
- [当前实现状态](current-state.md)：仓库现实状态、已完成任务、下一步可做任务。
- [当前实现状态](current-state.md)：可覆盖的当前快照，记录仓库现实状态、可运行命令和下一步可做任务。
## 任务 / 进度 / 当前状态
- `06-tasks.md` 维护任务看板：任务 ID、依赖、验收要点和状态。
- `../progress.md` 维护执行进度：每轮实际做了什么、跑了什么验证、遇到什么阻塞、做了什么决策。
- `current-state.md` 维护当前快照：当前目录、当前可运行命令、已完成任务摘要和下一个可领取任务。
如果新项目希望任务看板放在根目录，可把 `06-tasks.md` 复制或改名为根目录 `tasks.md`，并同步更新本文、`00-ai-start-here.md` 和 `current-state.md` 的链接。
## 维护原则
- 需求变化先改文档，再改代码。
- 代码现实变化后同步 `current-state.md` 和 `06-tasks.md`。
- 代码现实变化后同步 `current-state.md` 和 `06-tasks.md`，执行过程追加到 `../progress.md`。
- API、数据模型、路由、技术栈一旦在文档中定稿，代码不得另起一套。
- agent 开始新任务前，必须从 `00-ai-start-here.md` 进入。
docs/api.md
+59 -3
View File
@@ -1,8 +1,9 @@
# API 合约
# API / 模块合约
> 本文定义后端 API 的目标形状。实现前可细化，但不要在代码里另起一套不兼容接口。
> 本文定义后端 API、本地模块、CLI 参数或事件合约的目标形状。
> 实现前可细化，但不要在代码里另起一套不兼容接口。
如果项目没有后端 API，可改成本地模块接口、CLI 参数或事件合约。
如果项目没有后端 API，删除不适用的小节，改成本地模块接口、CLI 参数或事件合约。不要默认所有项目都有 REST 后端。
## 通用约定
@@ -78,6 +79,60 @@
成功响应返回新增资源。
## 无后端项目替代写法
用于桌面工具、CLI、本地自动化脚本、纯前端本地应用等没有后端服务的项目。
### 本地模块合约
```ts
type Input = {
sourcePath: string;
options: {
dryRun: boolean;
};
};
type Result = {
ok: boolean;
outputPath?: string;
errors: Array<{
code: string;
message: string;
}>;
};
```
需要写清楚：
- 模块入口函数：【函数名 / 文件路径】。
- 输入字段：【字段、类型、必填、默认值】。
- 输出字段：【成功结果、失败结果、错误码】。
- 副作用：【读写哪些文件、调用哪些系统能力、是否联网】。
### CLI 参数合约
```bash
【命令】 --input 【路径】 --output 【路径】 --dry-run
```
需要写清楚：
- 必填参数和可选参数。
- 默认值。
- 退出码含义。
- 标准输出和错误输出格式。
### 事件合约
适用于桌面 UI、浏览器本地状态、插件或自动化流程。
| 事件 | 触发时机 | 负载 | 结果 |
| --- | --- | --- | --- |
| 【event.name】 | 【用户动作 / 系统动作】 | 【字段】 | 【状态变化】 |
需要写清楚事件来源、负载字段、状态变化和失败处理。
## 待实现时确认
- 参数校验规则。
@@ -85,3 +140,4 @@
- 重复提交是否幂等。
- 错误码枚举。
- 鉴权过期时间和刷新策略。
- 无后端项目的模块入口、CLI 参数、事件负载和副作用边界。
docs/current-state.md
+16 -3
View File
@@ -1,6 +1,13 @@
# 当前实现状态
> 本文记录代码与任务看板的现实状态，帮助 AI coding agent 避免只看计划而忽略仓库现状。
> 本文是可覆盖的当前快照，记录代码与任务看板的现实状态，帮助 AI coding agent 避免只看计划而忽略仓库现状。
> 历史执行流水追加到 [`../progress.md`](../progress.md)，不要在本文重复维护完整执行日志。
## 职责边界
- [`06-tasks.md`](06-tasks.md)：任务看板，维护任务状态、依赖和验收要点。
- [`../progress.md`](../progress.md)：执行流水，只追加记录每轮执行、验证、阻塞和决策。
- `current-state.md`：当前快照，可覆盖更新当前目录、当前命令、已完成摘要和下一步。
## 当前快照
@@ -17,13 +24,13 @@
| --- | --- | --- |
| `docs/` | 已有 | 项目规范化文档 |
| `src/` | 【已有 / 待建】 | 前端或核心代码 |
| `server/` | 【已有 / 待建】 | 后端代码 |
| `server/` | 【已有 / 待建 / 不适用】 | 后端代码；无后端项目可删除或替换为核心模块目录 |
| `tests/` | 【已有 / 待建】 | 测试 |
| `scripts/` | 【已有 / 待建】 | 辅助脚本 |
## 任务看板状态
以 [`06-tasks.md`](06-tasks.md) 为准。
任务状态以 [`06-tasks.md`](06-tasks.md) 为准，历史执行记录见 [`../progress.md`](../progress.md)。
- 已完成：【列出 DONE 任务】。
- 正在进行：【如有，列出 DOING 任务】。
@@ -61,3 +68,9 @@
- 任务从 `TODO` 进入 `DOING` 或 `DONE`。
- 新增可运行命令。
- 发现文档和代码现实不一致。
同时注意：
- 任务状态变化必须同步 [`06-tasks.md`](06-tasks.md)。
- 每轮执行记录、验证命令、阻塞点和关键决策追加到 [`../progress.md`](../progress.md)。
- 本文件只保留当前快照，不保留完整历史。
progress.md
+31
View File
@@ -0,0 +1,31 @@
# 执行进度记录
> 本文件是只追加的历史流水，用来记录任务执行过程、验证命令、阻塞点和关键决策。
> 当前目录、当前命令、下一个可领取任务等可覆盖快照，写入 [`docs/current-state.md`](docs/current-state.md)。
## 职责边界
- `docs/06-tasks.md`：任务看板，维护任务状态、依赖和验收要点。
- `progress.md`：历史流水，只追加记录每轮执行发生了什么。
- `docs/current-state.md`：当前快照，可覆盖更新仓库现实、可运行命令和下一步。
不要在本文重复维护当前目录结构、当前运行命令或下一个任务；这些信息以 `docs/current-state.md` 为准。
## 记录格式
每完成或中断一轮任务，在文件末尾追加一条记录：
```markdown
## 【YYYY-MM-DD】T-【编号】 【任务名】
- 状态：【DONE / BLOCKED / PARTIAL】
- 变更：【修改了哪些文件或模块】
- 验证：【运行的真实命令和结果】
- 阻塞：【如有，写明原因和需要谁决策】
- 决策：【如有，记录本轮确定的关键取舍】
- 下一步：【建议下一个任务 ID 或待确认事项】
```
## 执行记录
<!-- 新项目开始后，从这里向下追加记录。 -->
tasks.md
+4 -3
View File
@@ -25,9 +25,9 @@ Get-ChildItem -Recurse -File
| ID | 任务 | 依赖 | 验收要点 | 状态 |
| --- | --- | --- | --- | --- |
| H-001 | 建立 Codex 入口 `AGENTS.md` | - | 说明仓库定位、必读顺序、工作规则和验证方式 | DONE |
| H-002 | 建立 Claude Code 入口 `CLAUDE.md` | - | 说明 Claude Code 读取顺序、模板边界和禁止事项 | DONE |
| H-002 | 建立 Claude Code 入口 `CLAUDE.md` | - | 作为薄入口指向 `AGENTS.md`，不重复维护规则和文档清单 | DONE |
| H-003 | 建立根目录总览 `README.md` | - | 说明样本库用途、推荐文档集合和使用方式 | DONE |
| H-004 | 明确 `docs/` 是 harness coding 文档目录 | H-001, H-002 | `AGENTS.md` 和 `CLAUDE.md` 均说明编程从 `docs/00-ai-start-here.md` 进入 | DONE |
| H-004 | 明确 `docs/` 是 harness coding 文档目录 | H-001, H-002 | `AGENTS.md` 说明编程从 `docs/00-ai-start-here.md` 进入，`CLAUDE.md` 指向 `AGENTS.md` | DONE |
| H-005 | 建立样本库任务列表 `tasks.md` | H-001 | 根目录存在维护任务列表，并和 `docs/06-tasks.md` 职责区分清楚 | DONE |
## Phase 1 · 核心模板
@@ -50,12 +50,13 @@ Get-ChildItem -Recurse -File
| H-201 | 建立 API 合约模板 `docs/api.md` | H-106 | 能记录接口形状、错误格式、鉴权和示例 | DONE |
| H-202 | 建立路由模板 `docs/routes.md` | H-106 | 能记录页面路由、组件归属和导航规则 | DONE |
| H-203 | 建立当前状态模板 `docs/current-state.md` | H-108 | 能记录仓库现实、已完成内容、可运行命令和下一步 | DONE |
| H-204 | 建立执行进度模板 `progress.md` | H-108 | 能追加记录任务执行、验证命令、阻塞点和关键决策 | DONE |
## Phase 3 · 一致性维护
| ID | 任务 | 依赖 | 验收要点 | 状态 |
| --- | --- | --- | --- | --- |
| H-301 | 检查入口文件之间的职责是否重复 | H-005 | `AGENTS.md`、`CLAUDE.md`、`README.md`、`docs/README.md`、`docs/00-ai-start-here.md` 各自职责清楚 | TODO |
| H-301 | 检查入口文件之间的职责是否重复 | H-005 | `AGENTS.md`、`CLAUDE.md`、`README.md`、`docs/README.md`、`docs/00-ai-start-here.md`、`progress.md` 各自职责清楚 | TODO |
| H-302 | 检查所有模板是否保持通用占位符 | H-201, H-202, H-203 | 没有混入只适用于某个真实项目的业务事实 | TODO |
| H-303 | 检查链接和文件名引用一致性 | H-301 | `rg` 搜索无旧名称、坏路径或冲突说明 | TODO |
| H-304 | 补充复制到新项目后的使用流程 | H-302 | README 和入口模板能指导用户从复制、替换占位符到开始编程 | TODO |