dev_harness/AGENTS.md

# Agent 开发规则

本仓库采用 DevHarness 工作流：Gitea 工单是任务过程的事实来源，Gitea Wiki 是长期开发文档和任务归档的事实来源，Git 是代码与版本绑定资料的变更记录，`docs/` 只保存 Wiki 的只读镜像。人负责确认方案与验收，Agent 负责检查、实现、测试和留下证据。

开始工作前先阅读 [项目档案](docs/00-project-profile.md) 和任务涉及目录中的 `AGENTS.md`。目录越深的规则越具体，但不得削弱上级安全规则。

## 1. 永久规则

- 不把密码、令牌、Cookie、私钥、个人数据或生产数据写入代码、日志、工单、Wiki 和文档。
- 不执行未经用户明确授权的发布、付款、删除数据、破坏性迁移或其他不可逆操作。
- 保留用户已有和任务无关的工作区改动，不擅自重置、覆盖或混入提交。
- 发现需求与安全规则、已确认方案或现有数据冲突时，先停止实施并说明影响。
- 测试结果必须真实；未执行或无法覆盖的验证必须明确记录。

项目专用红线写入本文件的“项目专用规则”或对应子目录的 `AGENTS.md`，不要散落在聊天记录中。

## 2. 哪些改动需要工单

新功能、缺陷修复、重构以及任何用户可感知或改变程序行为的修改，必须先建立单元任务工单。

以下小改动可以直接提交，不要求工单和任务归档：

- 只改错别字、注释或文档措辞；
- 只做格式化、导入排序或不跨文件的内部变量改名；
- 补充类型标注或文档字符串且不改变行为；
- 删除已经确认无人使用的死代码。

只要涉及接口、数据库、状态、权限、安全、并发、用户界面，或者无法确定是否改变行为，就必须建工单。

## 3. 需求到实施

1. 先复述目标，阅读相关代码、日志和文档，区分事实与假设。
2. 给出目标、非目标、方案、影响范围、风险、回退方式、验证方法和文档影响。
3. 方案没有得到用户明确确认前，只做只读诊断和方案整理，不实施正式代码。
4. 方案确认后，先建立单元任务工单，再修改代码。
5. 开始实施前检查分支和工作区，明确哪些现有改动不属于本任务。
6. 严格按工单范围实现；新发现的问题先记录，不顺手混入当前任务。
7. 执行与风险相称的测试，把关键结果和未验证部分更新到工单。
8. 长期文档必须先修改 Wiki、读取确认，再运行 `python dev_scripts/sync_wiki_docs.py` 导出本地镜像；不得直接编辑 `docs/` 后反向覆盖 Wiki。

Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明确授权，不得默认绕过建单。

### 效率与范围控制

本节只用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、Wiki 同步、Git 提交和验收归档要求。

#### 严格控制范围

- 默认严格按用户确认的目标和单元任务范围执行，不主动扩展相邻问题。
- 除非任务目标、仓库强制规则或已发现的真实阻塞需要，不新增额外文档、辅助脚本、备份文件、框架、重构或扩展性设计。
- 不执行与本次验收无关的验证；安全检查、受影响范围测试、回归测试和仓库规定的闭环验证不属于“额外验证”。
- 新发现的相邻问题最多用一句话提示或记录到独立工单，不自动修复或混入当前提交。

#### 渐进执行和修复

- 完成已知必要的安全与前置检查后，优先执行能够产生真实反馈的最小命令。
- 一次执行后先处理首个可定位、可行动的真实错误，不同时猜测并修改多个可能原因。
- 采用“执行 → 查看错误 → 最小修复 → 从失败点继续或按需重跑”的闭环。
- 不在真实证据出现前堆叠与已知风险无关的预防性检查。
- 涉及凭据、权限、安全、数据、迁移、并发、删除、发布或不可逆操作时，必须先完成相应前置检查，不得通过试错获取风险反馈。

#### 复用已验证事实

- 在同一任务和同一环境状态下，已经通过的路由、连接、恢复和环境检查不重复执行。
- 只有会话、环境、代码、配置、依赖、凭据、远端状态或关键前提发生变化时才重新检查。
- 代码修改后，受影响测试和最终验收必须重新执行；提交前工作区检查、推送前远端分支检查不得因为之前通过而省略。
- Skill 和平台规则是否需要重新读取，按当前 Agent 平台和任务触发规则执行，不自行跳过。

#### 明确停止条件

- 完成用户确认的验收标准和仓库规定的必要闭环后立即停止，不主动继续优化。
- “最小验收条件”包括当前工单要求的实现、必要测试、文档影响处理、Wiki 镜像检查、提交和证据回写，不等同于功能第一次运行成功。
- 未影响当前验收的相邻问题只提示或建单，不顺手处理。

## 4. 工单层级

```text
Epic：完整产品目标和长期路线
└── MVP：第一个可交付版本
    └── 单元任务：唯一的实施单位
```

- Epic 维护总体目标、范围、路线、风险和所有任务索引。
- MVP 维护首个可交付范围、阶段、集成风险和任务清单。
- 单元任务记录具体方案、修改范围、验收标准、过程和测试结果。
- 父工单只维护 `- [ ] #编号` 或 `- [x] #编号` 的索引和汇总，不复制子工单全文。
- 新任务先建单元工单，再把编号同步到所属 MVP 和 Epic。

工单模板位于 `.gitea/issue_template/`。

## 5. 实施中的变化

- 范围、接口、数据结构、依赖、验收标准或风险变化时，先更新单元工单。
- 变化影响 MVP 或 Epic 时，同时更新父工单。
- 会改变用户已确认结果的变化，更新工单后必须再次等待用户确认。
- 阻塞、失败方案和新发现根因不能只留在聊天或代码注释中。
- Wiki 页面删除、重命名或事实源边界变化时，必须先更新工单并等待用户确认；同步工具不得自动传播删除或重命名。
- 工单状态应使用：待确认、待实施、进行中、阻塞、待验收、已完成。

## 6. Git 与验证

- 提交只包含当前工单相关文件。
- 实现提交信息引用工单号，例如：`fix: 修复登录超时 (#123)`。
- 不为流程制造空提交。
- 优先运行项目档案中记录的格式检查、静态检查、单元测试和必要的集成测试。
- 不能验证的真机、生产、迁移或并发行为必须写入工单和归档。

## 7. 完成、验收和归档

1. 实现完成后逐项检查验收标准，并提交代码。
2. 更新单元工单：最终方案、方案差异、测试结果、提交哈希和遗留问题。
3. 工单保持“待验收”，用户没有明确验收通过前不得关闭。
4. 运行 `python dev_scripts/new_task_archive.py <编号> "<短标题>"`，先在 Wiki 创建任务归档，再登记映射并导出 `docs/task/<编号>-<短标题>.md` 镜像。
5. 读取确认 Wiki 页面，运行 `python dev_scripts/sync_wiki_docs.py --check` 校验镜像。
6. 归档镜像单独提交，例如：`docs: 归档任务 #123`。
7. 把 Wiki 页面、revision、镜像路径和提交哈希回写工单。
8. 用户验收通过后关闭单元工单，并同步更新 MVP 和 Epic。

MVP 内所有单元任务通过后才能做 MVP 集成验收；MVP 通过后才能关闭 MVP。Epic 的全部范围完成后才能关闭 Epic。

## 8. 可维护性

- 优先使用直白、常见的实现；不要为了少写几行引入晦涩技巧。
- 类和函数保持单一职责，名称表达业务含义。
- 注释解释原因、边界和风险，不逐行翻译代码。
- 错误必须可定位，不静默吞掉失败。
- Wiki 文档先写结论和用途，再写步骤；示例命令应可直接复制，本地 `docs/` 由同步工具生成。
- 面向初级维护者说明从哪里开始读、怎样运行和怎样验证。

### 初级维护者的修改边界

| 风险 | 示例 | 处理方式 |
|---|---|---|
| 低 | 文案、简单校验、查询条件、独立 UI、小范围回归 Bug | 初级程序员可在 Agent 协助下理解、修改和验证 |
| 中 | API、配置、依赖、跨模块逻辑、数据结构 | 由 Agent 实现，程序员检查差异并执行验证 |
| 高 | 权限、安全、并发、迁移、支付、删除数据、不可逆操作 | 停止修改，由 Agent 分析并等待人工确认 |

风险按影响范围判断，不按代码行数判断。

### 核心文档与更新条件

- 新项目至少维护：新人入口、项目档案、架构与代码地图、业务规则与术语、本地开发与验证、常见修改、故障排查、开发工作流和任务归档模板。
- 每个单元任务必须在工单中选择“无长期文档影响并说明原因”或列出需要更新的 Wiki 页面。
- 启动、测试、部署、排错命令，模块入口、目录职责、主要调用路径，配置、API、数据结构、状态、业务规则、安全边界、日志位置发生变化时，必须更新对应 Wiki。
- 普通内部重构只有在入口、行为、配置和验证方式均未改变时，才可以记录为不影响长期文档。
- 稳定主题页描述项目现在怎样工作；工单和任务归档只解释某次为什么修改以及如何验证。新人不应依赖按时间阅读任务归档来理解当前系统。

## 9. 引导提交例外

从本模板创建全新仓库时，Gitea 远端和工单尚不存在，允许一次不带工单号的初始引导提交。该提交只能包含仓库骨架、Harness 规则和远端配置准备，不能包含产品功能。

远端建立并推送后，这个例外立即失效。

## 10. 项目专用规则

<!-- 在项目初始化时填写不可违反的技术、安全和业务约束。复杂子项目请在其目录中增加 AGENTS.md。 -->

- 长期开发文档以 Gitea Wiki 为事实来源，`docs/` 是显式映射生成的只读镜像。
- Wiki 与镜像的固定顺序是：修改 Wiki → 读取确认 → 导出 `docs` → 校验差异 → 提交镜像。
- 同步配置只允许写入 `docs/` 下的 Markdown；发现镜像有未提交修改时必须停止。
- Gitea 凭据只通过进程环境或 MCP 安全配置提供，不得写入仓库。
- `dev_scripts/` 只存放 DevHarness 自身工具；业务项目的通用脚本必须使用独立目录，不得混放。