# Claude Code / Hermes 编码代理工作流规范

> 适用范围：本规范用于本地项目中的 AI 编码代理协作，尤其适合 Claude Code、Hermes Agent、Codex/Gemini 辅助审查等组合。
>
> 来源基础：整理自 Towards Data Science 文章《How to Write Robust Code with Claude Code》，并结合当前本地项目约束改写为可执行工作流。

## 1. 核心原则

编码代理的可靠性，不应主要依赖人工逐行审查，而应依赖一套可重复的工程流程：

1. 先规划，再实现。
2. 控制上下文，不让噪音淹没关键约束。
3. 把项目经验沉淀到仓库文档或 Hermes skill/wiki，而不是只留在聊天记录里。
4. 写代码代理和审查代理分离。
5. 所有完成声明必须有验证证据：测试、lint、diff、运行结果或人工确认点。

一句话版本：

> 让代理多做思考和复查，但让流程负责约束边界、验证结果和沉淀经验。

## 2. 角色分工

### 2.1 用户 / Owner

负责：

- 明确目标、边界和不可接受风险。
- 对真实生产副作用做最终确认，例如数据库变更、K8s 操作、部署、外部通知。
- 对关键方案、计划和最终交付做业务判断。

不需要做：

- 逐行审查所有 AI 生成代码。
- 手工重复执行机械检查。
- 记住每次 bug 的全部细节。

### 2.2 Hermes Agent

负责：

- 接收任务、判断是否需要先读代码/文档/历史上下文。
- 拆分任务、调用工具、必要时委派 subagent。
- 写计划、执行修改、运行验证。
- 将可复用经验沉淀到合适层级：项目文档、skill、wiki 或 memory。

### 2.3 Claude Code / 编码代理

负责：

- 根据明确计划完成实现。
- 主动发现不清楚的问题并提问。
- 遵守项目内 `CLAUDE.md`、`AGENTS.md`、README、测试约束。
- 不擅自扩大范围，不做未授权副作用。

### 2.4 独立审查代理

负责：

- 用干净上下文审查 diff / PR / 计划。
- 专注找遗漏、边界、回归、安全问题。
- 必要时使用不同模型，减少同模型盲区。

建议组合：

- Claude Code：主实现。
- Hermes：调度、验证、沉淀。
- Gemini / Codex / 另一个 Claude 会话：独立审查。

## 3. 标准任务流程

### 3.1 小任务流程

适用：文档修正、小 bug、局部脚本调整、无生产副作用的小改动。

步骤：

1. 读取相关文件和项目约束。
2. 明确最小修改范围。
3. 直接修改。
4. 运行最小验证：单测、lint、脚本 smoke test 或 diff 检查。
5. 汇报：改了什么、怎么验证、还有什么风险。

完成标准：

- diff 可解释。
- 至少有一个验证证据。
- 没有无关重构。

### 3.2 中等任务流程

适用：新增功能、重构局部模块、影响多个文件但不直接操作生产资源。

步骤：

1. 写一个短 plan，包含目标、非目标、涉及文件、验证方式。
2. 用户确认或默认边界足够清楚后执行。
3. 分阶段修改，每阶段保持可回滚。
4. 运行相关测试和静态检查。
5. 按需触发独立代理 review。
6. 如触发 review，根据审查结果修正或说明不采纳原因。
7. 输出完成报告。

独立 review 触发条件：

- 涉及核心业务逻辑。
- 跨多个模块或改动面较大。
- 测试覆盖不足，或只能做替代验证。
- 涉及安全、数据、权限、生产配置、外部副作用。
- 用户明确要求更稳健的审查。

完成标准：

- plan 与实际 diff 对齐。
- 测试通过或失败原因明确。
- 触发 review 时，审查结果已处理；未触发时，需说明主要验证依据。
- 没有越权修改生产敏感文件。

### 3.3 高风险任务流程

适用：数据库、K8s、部署、权限、安全、账务、生产告警、外部 API 写入。

步骤：

1. 先输出操作计划，不直接执行。
2. 明确：目标、影响范围、回滚方案、验证方式、停止条件。
3. 等用户确认后再执行有副作用步骤。
4. 优先 dry-run、只读检查、备份、分批执行。
5. 执行后立即验证。
6. 记录变更证据和后续观察项。

硬规则：

- 不经确认，不执行破坏性操作。
- 不经确认，不改数据库事务管理核心逻辑。
- 不硬编码密码、IP、Token。
- 不为了通过测试而删除/跳过测试。

## 4. Plan Mode 使用规范

### 4.1 什么时候必须先 plan

以下情况必须先 plan：

- 任务跨多个文件或模块。
- 涉及数据库、K8s、系统服务、部署、权限。
- 用户要求“重构”“优化”“接入”“治理”“规范化”。
- 需求存在明显歧义。
- 修改可能影响现有行为。

### 4.2 一个合格 plan 应包含

建议模板：

```markdown
# Plan: <任务名>

## 目标
- ...

## 非目标
- ...

## 现状依据
- 已读取文件：...
- 已确认约束：...

## 修改步骤
1. ...
2. ...
3. ...

## 验证方式
- ...

## 风险与回滚
- 风险：...
- 回滚：...

## 需要用户确认的问题
- ...
```

### 4.3 Plan Mode 的关键要求

- 让代理主动提问题，而不是带着歧义开写。
- plan 要能指导执行，不写空泛原则。
- 用户确认前，不做高风险副作用。
- 执行中发现计划错误，应更新计划或暂停确认。

## 5. 上下文管理规范

### 5.1 上下文只放必要信息

优先放：

- 当前任务目标。
- 相关文件内容。
- 项目约束文件：`CLAUDE.md`、`AGENTS.md`、README、测试说明。
- 最近失败日志。
- 明确的用户限制。

避免放：

- 大量无关历史聊天。
- 无关模块源码。
- 过期计划。
- 长篇工具输出原文。

### 5.2 大上下文的处理方式

如果上下文过大：

1. 先摘要成“任务相关事实”。
2. 把长期有效规则写入项目文档或 skill。
3. 把临时过程留在会话，不写入 memory。
4. 必要时新开干净审查上下文。

实用规则：

> 宁可给代理一份短而准确的约束清单，也不要给它一大堆未经筛选的历史材料。

## 6. 项目知识沉淀规范

### 6.1 分层原则

不同知识放在不同位置：

- `CLAUDE.md` / `AGENTS.md`：项目级硬约束和常用命令。
- `docs/`：设计决策、操作手册、长期规范。
- Hermes skill：可跨项目复用的流程。
- wiki：概念、原则、领域知识。
- memory：稳定偏好和环境事实，不放临时任务进度。

### 6.2 每次任务后的沉淀判断

任务完成后问三个问题：

1. 这个经验下次还会用吗？
2. 它是项目特有，还是跨项目通用？
3. 它一周后还有效吗？

推荐处理：

- 项目特有且长期有效：写项目文档。
- 跨项目流程：写 Hermes skill。
- 概念性知识：写 wiki。
- 临时结果、PR 号、一次性修复：不沉淀到 memory。

### 6.3 Bug 修复记录模板

```markdown
## Bug: <简短标题>

### 现象
- ...

### 根因
- ...

### 修复
- ...

### 防复发规则
- ...

### 验证
- ...
```

## 7. 编码代理实现规范

### 7.1 实现前

代理必须先确认：

- 已读取相关代码。
- 已读取项目约束文件。
- 已知道测试命令。
- 已明确不该改哪些文件。

### 7.2 实现中

要求：

- 最小修改，不顺手重构。
- 新增函数要有类型注解。
- 遵守项目命名、日志、异常规范。
- 不引入新依赖，除非用户确认。
- 不硬编码密钥、IP、Token。
- 涉及外部命令时避免 `shell=True`。

### 7.3 实现后

必须验证：

- 运行相关测试。
- 检查 diff。
- 对改动行为做 smoke test 或最小复现。
- 如果测试无法运行，说明原因和替代验证。

## 8. 独立 Code Review 规范

### 8.1 什么时候需要独立 review

建议触发条件：

- 改动超过一个模块。
- 修改业务逻辑、权限、数据处理、调度、通知。
- 用户明确要求稳健性。
- 测试覆盖不足。
- 代码由一个代理大段生成。

### 8.2 审查提示词模板

```text
你是独立代码审查代理。请只审查以下变更，不要修改文件。

审查目标：
1. 找出可能的 bug、边界遗漏、回归风险。
2. 检查是否违反项目约束。
3. 检查测试是否覆盖核心路径。
4. 区分必须修复、建议修复、可忽略问题。

项目约束：
- <粘贴关键 CLAUDE.md / AGENTS.md 约束>

变更范围：
- <文件列表或 diff>

输出格式：
- 结论：通过 / 需要修改
- 必须修复：...
- 建议修复：...
- 测试缺口：...
- 依据：...
```

### 8.3 审查结果处理

处理规则：

- 必须修复项：修复或明确说明为什么误报。
- 建议项：按收益/风险选择性采纳。
- 风格项：除非项目已有规范，否则不扩大改动。
- 审查分歧：优先采取更保守、可回滚的方案。

## 9. Pre-commit 与生产就绪检查

### 9.1 自动检查

每个项目应尽量具备：

- 格式化检查。
- lint。
- 类型检查。
- 单元测试。
- 安全/密钥扫描。
- 项目特定静态规则。

Python 项目推荐：

```bash
pytest -q
ruff check .
ruff format --check .
ty check .  # 如果项目使用 ty
```

当前旧项目按项目文档为准，例如 `excsql` 使用：

```bash
cd ~/code/project/work/excsql
source .venv/bin/activate
pytest tests/ -v
```

### 9.2 代理生产就绪检查

提交前可让代理回答：

```text
请检查当前变更是否 production ready。
重点看：
1. 是否有未处理异常或边界情况。
2. 是否有安全风险、密钥泄露、权限问题。
3. 是否有数据破坏或不可回滚风险。
4. 是否有测试缺口。
5. 是否违反项目 CLAUDE.md / AGENTS.md。
只输出问题，不要泛泛表扬。
```

## 10. 本地项目推荐落地方式

### 10.1 对 `excsql`

必须遵守：

- 修改前跑现有测试或至少明确当前测试基线。
- 禁止修改 `core/db_executor.py` 事务管理逻辑，除非单独确认。
- 新功能必须有 mock 测试。
- SQL 执行、备份、归档、通知相关改动要保守。

建议流程：

1. 先写 plan 到 `.hermes/plans/` 或项目 docs。
2. 用户确认边界。
3. 小步修改。
4. `pytest tests/ -v`。
5. 按触发条件决定是否做独立代理 review。
6. 再决定是否提交。

Plan 管理要求：

- 临时 plan 完成后应清理或归档到合适的项目文档。
- 不把一次性任务进度长期堆在 `.hermes/plans/`。
- 只有长期有效的约束、决策和复盘结论才沉淀到项目 docs / skill / wiki。

### 10.2 对 K8s / 运维监控项目

必须遵守：

- 任何真实 K8s / 系统服务操作前先输出操作计划。
- 默认先 dry-run 或只读检查。
- 告警通知要防重复、防刷屏。
- Webhook 和 token 只能从环境变量或 `.env` 读取。

建议验证：

- mock K8s API。
- mock 企业微信 webhook。
- 单测覆盖状态机、去重、恢复通知。

### 10.3 对新 Python 项目

默认模板：

- Python 3.13。
- uv。
- Ruff。
- Ty。
- pytest。
- `.env.example` + `.gitignore`。
- `README.md` 写清运行和测试命令。
- `AGENTS.md` 或 `CLAUDE.md` 写清代理约束。

## 11. 完成报告模板

每次任务结束时，建议输出：

```markdown
完成：<一句话结论>

改动：
- ...

验证：
- ...

风险/未做：
- ...

建议下一步：
- ...
```

如果验证失败：

```markdown
未完成：<失败原因>

已完成：
- ...

失败证据：
- 命令：...
- 错误：...

建议下一步：
- ...
```

## 12. 推荐默认工作流

最终推荐采用下面这条默认链路：

```text
需求输入
→ 读取项目约束和相关代码
→ Plan Mode / 写短计划
→ 用户确认高风险边界
→ 编码代理实现
→ 本地测试和静态检查
→ 独立代理 review
→ 修正问题
→ 输出验证证据
→ 判断是否沉淀项目知识或 skill
```

这条链路的目标不是让流程变复杂，而是避免最常见的 AI 编码失败：

- 没读项目约束就开写。
- 上下文太大导致忽略关键规则。
- 一个代理既写又自夸式审查。
- 没有测试就宣布完成。
- 同样的坑反复踩，却没有沉淀。

## 13. 最小可执行版本

如果只想先落地最小版本，执行这 5 条即可：

1. 中等以上任务先写 plan。
2. 每次修改前读 `CLAUDE.md` / `AGENTS.md`。
3. 每次完成必须跑测试或说明替代验证。
4. 重要改动用另一个代理审查。
5. 修过的典型 bug 写进项目文档或 skill。

这已经能覆盖大多数 Claude Code / Hermes 协作中的可靠性问题。