harness_coding_docs/docs/05-coding-rules.md

# 编码规则（Coding Rules）

> 每次写代码前先读完本文件。这是让 AI 不跑偏、代码质量稳定的硬约束。
> 与技术细节冲突时，以 [技术栈](03-tech-stack.md) / [架构设计](04-architecture.md) 的事实为准；与“该不该做”冲突时，以 [需求](02-requirements.md) 为准。

## 0. 黄金法则

1. **不臆造**：数据字段、文件、接口、依赖，不确定就查证或询问。
2. **守范围**：只做当前任务要求的事，不顺手加后续功能。
3. **照架构**：使用既定技术栈和模块边界，不擅自引入新框架。
4. **小步改**：一次只解决一个问题，不夹带无关重构。
5. **可验证**：改完必须能构建、能测试、对得上验收标准。

## 1. 动手前

- 涉及页面、表单、导航或用户可见状态时，先读取关联的 `07-user-stories.md`、`08-interaction-checklist.md`、`routes.md` 和验收标准。
- 按链路确认：`vision` -> `requirements` -> `tech-stack` -> `architecture` -> `tasks`。
- 找到本任务对应的验收标准，写之前就知道“怎么算做对”。
- 复杂任务先把确认后的方案、不可变约束、`write_paths` 和验证层级写入任务文件；不要让关键决策只停留在对话里。
- 先找现有函数、组件、工具和测试，复用优先。
- 如果需求含糊，或改动会偏离原则 / 架构，先问。

## 2. 事实来源纪律

- 只相信文档指定的权威数据源、schema、API 合约和当前代码。
- 不从备份、草稿、旧导出文件里推断当前事实。
- 不虚构字段、接口、状态码、配置项。
- 数据结构变化必须同步更新 `04-architecture.md`、`api.md` 和相关任务。

## 3. 范围纪律

- MVP 只做 `02-requirements.md` 中列为 P0 的功能。
- V2 / V3 功能只记录，不实现。
- 需求明确排除的非目标不得实现。
- 不为“将来可能用到”提前抽象。

## 4. 架构纪律

- 技术栈以 `03-tech-stack.md` 为准。
- 新增依赖前先说明理由；未经确认不要引入重量级依赖。
- 模块职责以 `04-architecture.md` 为准，不跨层偷写逻辑。
- API、本地模块、CLI 或事件合约以 `api.md` 为准，页面路由以 `routes.md` 为准。

## 5. 代码规范

- 标识符使用英文。
- UI 文案、注释、文档语言按项目现状保持一致。
- 错误必须处理，不吞错。
- 注释解释“为什么”，不复述“做了什么”。
- 遵守项目已有格式化工具，不手工制造风格分裂。

## 6. 测试与验证

任务所有者（未委派时即当前 agent）必须亲自完成最终复核：

1. 用 `git status --short` 核对实际修改集合，同时审阅 `git diff` 和 `git diff --cached`，对照任务的 `write_paths`、不可变约束和验收要点，避免漏掉已暂存改动。
2. 用 `git diff --check` 和仓库既有格式化 / `.gitattributes` 规则检查空白与意外行尾变化；不要把某一种行尾格式硬编码成所有项目的通用要求。
3. 按 [`03-tech-stack.md`](03-tech-stack.md) 的验证矩阵独立重跑任务相关验证；命中完整门禁触发条件时再跑完整门禁。
4. 执行者、子 Agent、工具或 CI 的摘要只能作为线索，不能替代任务所有者看到的差异和可复现验证结果。
5. 必需的人工 / 设备验收尚未完成时，记录等待事项并保持 `DOING` 或 `BLOCKED`，不得标记 `DONE`。

完成前至少检查：

- [ ] 构建通过。
- [ ] 相关测试通过。
- [ ] 已按验证矩阵判断是否需要完整门禁，并完成所有已触发层级。
- [ ] 对得上需求验收标准。
- [ ] 没有夹带无关改动。
- [ ] `git status`、未暂存 / 已暂存 diff 与任务 `write_paths`、不可变约束一致，未出现意外行尾变化。
- [ ] 必需的人工 / 设备验收已完成；不适用时已在任务文件说明。
- [ ] 涉及文档事实变化时，文档已同步。
- [ ] 涉及 UI 时，已验证关联 US / IX 的正常、加载、异常、权限和无障碍要求，或记录明确的不适用理由。
- [ ] 已在当前任务文件（`docs/tasks/T-<编号>.md`）的 `## 执行记录` 记录跑过的命令和结果作为证据（约定见 [`tasks/README.md`](tasks/README.md)），不靠"代码已写"判定完成。
- [ ] 回复里如实说明跑了什么命令、结果如何。

把真实命令填在这里：

```bash
# 示例
npm test
npm run build
go test ./...
```

## 7. 绝不

- 绝不把密钥、token、密码写进代码或文档样例的真实值里。
- 绝不为了让测试通过而删除断言、降低验收标准。
- 绝不擅自删除用户已有文件或重置工作区。
- 绝不在没说明的情况下改公共接口、迁移数据结构或升级依赖。

## 8. 安全与合规

- 敏感信息只能使用占位符或环境变量名，不写真实账号、密钥、token、Cookie、私有 URL。
- 涉及第三方平台时，先在 `02-requirements.md` 或 `04-architecture.md` 写清平台规则、调用边界、限流和失败处理。
- 涉及资金、账号、权限、隐私数据或不可逆操作时，必须有显式验收标准和安全校验。
- 自动化脚本默认先支持 dry-run、日志和人工确认；批量提交、批量删除、批量发送等动作必须有边界和回滚说明。
- 不绕过平台限制、验证码、风控或权限校验。

## 9. 拿不准就问

问题要具体，说明你卡在哪里、有哪些选项、倾向哪个选项以及原因。