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 应包含
建议模板：
# 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 修复记录模板
## Bug: <简短标题>
### 现象
- ...
### 根因
- ...
### 修复
- ...
### 防复发规则
- ...
### 验证
- ...7. 编码代理实现规范
7.1 实现前
代理必须先确认：
- 已读取相关代码。
- 已读取项目约束文件。
- 已知道测试命令。
- 已明确不该改哪些文件。
7.2 实现中
要求：
- 最小修改，不顺手重构。
- 新增函数要有类型注解。
- 遵守项目命名、日志、异常规范。
- 不引入新依赖，除非用户确认。
- 不硬编码密钥、IP、Token。
- 涉及外部命令时避免
shell=True。
7.3 实现后
必须验证：
- 运行相关测试。
- 检查 diff。
- 对改动行为做 smoke test 或最小复现。
- 如果测试无法运行，说明原因和替代验证。
8. 独立 Code Review 规范
8.1 什么时候需要独立 review
建议触发条件：
- 改动超过一个模块。
- 修改业务逻辑、权限、数据处理、调度、通知。
- 用户明确要求稳健性。
- 测试覆盖不足。
- 代码由一个代理大段生成。
8.2 审查提示词模板
你是独立代码审查代理。请只审查以下变更，不要修改文件。
审查目标：
1. 找出可能的 bug、边界遗漏、回归风险。
2. 检查是否违反项目约束。
3. 检查测试是否覆盖核心路径。
4. 区分必须修复、建议修复、可忽略问题。
项目约束：
- <粘贴关键 CLAUDE.md / AGENTS.md 约束>
变更范围：
- <文件列表或 diff>
输出格式：
- 结论：通过 / 需要修改
- 必须修复：...
- 建议修复：...
- 测试缺口：...
- 依据：...8.3 审查结果处理
处理规则：
- 必须修复项：修复或明确说明为什么误报。
- 建议项：按收益/风险选择性采纳。
- 风格项：除非项目已有规范，否则不扩大改动。
- 审查分歧：优先采取更保守、可回滚的方案。
9. Pre-commit 与生产就绪检查
9.1 自动检查
每个项目应尽量具备：
- 格式化检查。
- lint。
- 类型检查。
- 单元测试。
- 安全/密钥扫描。
- 项目特定静态规则。
Python 项目推荐：
pytest -q
ruff check .
ruff format --check .
ty check . # 如果项目使用 ty当前旧项目按项目文档为准，例如 excsql 使用：
cd ~/code/project/work/excsql
source .venv/bin/activate
pytest tests/ -v9.2 代理生产就绪检查
提交前可让代理回答：
请检查当前变更是否 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. 完成报告模板
每次任务结束时，建议输出：
完成：<一句话结论>
改动：
- ...
验证：
- ...
风险/未做：
- ...
建议下一步：
- ...如果验证失败：
未完成：<失败原因>
已完成：
- ...
失败证据：
- 命令：...
- 错误：...
建议下一步：
- ...12. 推荐默认工作流
最终推荐采用下面这条默认链路：
需求输入
→ 读取项目约束和相关代码
→ Plan Mode / 写短计划
→ 用户确认高风险边界
→ 编码代理实现
→ 本地测试和静态检查
→ 独立代理 review
→ 修正问题
→ 输出验证证据
→ 判断是否沉淀项目知识或 skill这条链路的目标不是让流程变复杂，而是避免最常见的 AI 编码失败：
- 没读项目约束就开写。
- 上下文太大导致忽略关键规则。
- 一个代理既写又自夸式审查。
- 没有测试就宣布完成。
- 同样的坑反复踩，却没有沉淀。
13. 最小可执行版本
如果只想先落地最小版本，执行这 5 条即可：
1. 中等以上任务先写 plan。 2. 每次修改前读 CLAUDE.md / AGENTS.md。 3. 每次完成必须跑测试或说明替代验证。 4. 重要改动用另一个代理审查。 5. 修过的典型 bug 写进项目文档或 skill。
这已经能覆盖大多数 Claude Code / Hermes 协作中的可靠性问题。