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
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
+7 -1
View File
@@ -63,4 +63,10 @@
- 【风险 1】：【为什么有风险，建议先如何验证】。
- 【风险 2】：【数据、性能、授权、依赖、体验等风险】。
- 【待确认问题】：【谁来决策，什么时候需要决策】。
- 【资金风险】：【是否涉及付款、退款、分账、对账，谁确认规则】。
- 【账号 / 权限风险】：【是否涉及用户账号、平台账号、代操作权限或凭证保存】。
- 【第三方平台风险】：【是否依赖平台规则、限流、封号、接口变更或人工审核】。
- 【自动化边界风险】：【是否会自动点击、批量提交、爬取、发送消息或触发不可逆操作】。
- 【隐私数据风险】：【是否处理个人信息、敏感文件、聊天记录、定位、联系方式等】。
- 【合规风险】：【版权、平台条款、行业监管、数据跨境、审计留痕等是否需要确认】。
- 【待确认问题】：【谁来决策，什么时候需要决策】。
docs/04-architecture.md
+17 -5
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,13 +122,15 @@ project/
按实际技术栈替换：
- `src/`：【前端 / 客户端代码】
- `server/`：【后端代码】
- `server/`：【后端代码；无后端项目可删除或替换为核心模块目录】
- `scripts/`：【数据校验、迁移、构建辅助脚本】
- `tests/`：【测试目录】
路径只是模板占位，初始化后必须按真实技术栈和项目形态替换，不要保留误导性的空目录说明。
## 七、架构纪律
- 业务事实和 schema 变化必须同步更新本文。
- 不在代码里发明文档没有的接口、字段和状态。
- 不把静态内容、用户数据、缓存数据混在一个模型里。
- 高风险模块先单独验证，再接入完整页面或流程。
- 高风险模块先单独验证，再接入完整页面或流程。
docs/05-coding-rules.md
+11 -3
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
+5 -2
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 |
@@ -65,4 +68,4 @@
- 【V2 功能 1】
- 【V2 功能 2】
- 【优化项】
- 【优化项】
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)。
- 本文件只保留当前快照，不保留完整历史。