weichen/Agent-System
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
49fb68fec1ea56f00616c23d08efb15950c2300d
Agent-System/AGENTS.md
T
weichen 048bbe4a5e docs(workflow): require isolated worktrees for all new agent changes 
Adopt the approved workflow with explicit dev baselines, serialized candidate integration, scoped validation and safe cleanup. Keep automation work tracked separately from the active policy.
2026-09-21 08:08:14 +00:00

13 KiB
Raw Blame History

Agent 工作手册（通用）

本文件与具体业务仓库无关，可整文件复用到其他项目。
本仓库差异化约定见 PROJECT.md。

1. 目的与适用范围

  • 适用于在本仓库工作的所有编码 Agent（Cursor、Claude Code、Codex、Kimi、Antigravity 等）。
  • 聊天记录易失；Git 与活文档区才是可协作、可审计的真相来源。
  • 任何任务、调研、审计、修复、运维操作均须同步落盘，禁止「只改代码 / 只留在对话」。

2. 启动协议（Session Bootstrap）

每次会话开始，按顺序阅读：

  1. 本文件 AGENTS.md
  2. PROJECT.md（本仓库地图与约定）
  3. .doc/README.md（文档 taxonomy）
  4. .doc/ops/CURRENT.md（焦点、并行认领、集成槽位）
  5. .doc/status/FEATURE-MATRIX.md（模块完成度）
  6. 创建任务、合入、部署、清理前：读 worktree 工作规范（含自动化未落地时的操作方法）
  7. 相关 short-term / handoff / audit / remediation
  8. 发布/审计类任务：remediation/gap-matrix.md

未读完不得开始改代码（紧急热修除外，事后必须在 24h 内补文档）。

3. 文档同步红线（强制）

时机 必须动作
任务开始 在 short-term/ 或 long-term/ 新建或更新条目（复制 templates）
认领 在 CURRENT「并行认领」表登记 owner / branch / mutex
合 dev + 容器测 占用 CURRENT「集成槽位」；他人排队
里程碑 更新任务文 status、FEATURE-MATRIX、CURRENT
调研/审计 写入 audit/ 或 ops/research/
整改方案 写入 remediation/
验收 写 test-report（路径见 PROJECT），回链 checklist
会话结束/切换 Agent 按 session-close-checklist
提交 文档变更与代码同批或紧随 docs(...) 提交

状态字段：planned | in_progress | blocked | done | cancelled

current vs historical：完成项标 done 并移入 archive/；不删除证据。

4. 文档 taxonomy

默认路径：.doc/（详见 .doc/README.md）

.doc/
  README.md           # 总地图
  status/             # FEATURE-MATRIX（模块完成度 SSOT）
  audit/              # 问题发现与分析
  remediation/        # 整改方案；gap-matrix（发布 blocker）
  archive/            # 历史（只增不删）
  ops/                # 活协作：CURRENT、short-term、handoffs…
  system-design/      # 模块架构深读
  adr/ | backlog/ | test-reports/ | test-fixtures/

红线：禁止在 .doc/ 根或 docs/ 随意新建项目文档；新文档必须落入 taxonomy。

命名：YYYY-MM-DD-<slug>.md

5. 文档类型与何时使用

类型 路径 模板
问题/分析 audit/ audit-note.md
整改方案 remediation/ remediation-plan.md
短期任务 ops/short-term/ short-term-task.md
长期 backlog ops/long-term/ long-term-task.md
Checklist ops/checklists/ checklist.md
交接 ops/handoffs/ handoff.md
调研 ops/research/ research-note.md
模块完成度 status/FEATURE-MATRIX.md feature-matrix-row.md
验收报告 .doc/test-reports/ 见 test-reports-standard
历史 archive/** 关闭后迁入

6. 多 Agent 协作

6.1 任务与主目录边界

  • 主目录作为 dev 集成与运行入口；所有新增开发、配置、规范和文档改动，包括单 Agent 任务，均在 .worktrees/ 的任务 worktree 内完成。
  • 主目录跟踪文件只通过受控 Git 集成更新，不作日常编辑；.git、任务 worktree、服务运行数据和获授权的运维配置属于明确例外。禁止递归 chmod 整个主目录。
  • 一个任务一个 feature/<task-id> / fix/<task-id> 分支、一个 worktree，可包含多个原子提交。既有任务延续原任务分支；无关新任务重新从 dev 创建。
  • 已经在主目录运行的旧任务保留现场，由所有者完成或交接后迁移；其他 Agent 不得擅自 checkout、stash、reset、移动其未提交文件。
  • 任务必须登记 owner、branch、worktree、base_dev_sha、允许写路径、mutex、验证计划。CURRENT 保留认领快照；各 worktree 的 CURRENT 不构成原子锁。
  • 同一 mutex 或重叠写路径同时只允许一个写者；公共 lockfile、路由、迁移号单独认领。冲突时排队或写 handoff，不覆盖他人工作。

6.2 创建与开发

  1. 先核对仓库、主工作区、当前分支、工作树状态、已有 worktree 与任务认领。
  2. 由协调者管理 dev 同步；开发 Agent 不在共享主目录切分支或直接 pull。记录本地 dev 的确切 SHA 与远端同步状态，分叉时保留现场。
  3. 显式从该 base_dev_sha 创建 .worktrees/<task-id>，不能省略起点，也不从另一 feature 分支开新任务。
  4. 在任务 worktree 完成开发、原子提交、相应测试和文档；不复制主目录 .env、业务 data 或其他任务的可变产物。
  5. 提交集成前冻结 head SHA；变更超出允许范围时先重新认领，提交变化后原测试/审查准入失效。

当前脚本尚有错误起点和强制删除缺口，修复验收前不用 agent-worktree.sh create/remove；按 操作规范 使用带显式起点的 Git 命令和非强制清理。

6.3 串行集成与环境验收

  • 编码和隔离测试可并行；dev 合入、共享服务变更和共享环境验收必须串行，记录 CURRENT 槽位和共同 Git 目录中的执行锁。完整机器队列未实现时按操作规范手工持锁，不以 Markdown 的 idle 作为唯一准入。
  • 推荐在 .worktrees/ 内的临时 feature/integrate-* 上从 dev 基线生成 --no-ff 合并候选，验证该提交；锁内确认 dev 基线未变后，将干净 dev 工作区 --ff-only 推进至同一候选。dev 变化则重新组合并验证。
  • 业务冲突返回任务 worktree 解决；dev/test/main 禁止直接开发提交。迁移期间主目录被旧任务占用时，纯规范/文档可使用登记的临时 dev 集成 worktree，禁止由此操作共享服务；详见操作规范的收口条件。
  • Go 变更执行 PROJECT 的 Go/架构及相关 PG 检查；web 变更执行前端检查与受影响浏览器验证；涉及产品 PI 的业务交付执行真实链路验收。纯工程规范/文档只做对应一致性检查，不为形式重建服务。
  • 影响运行内容的改动合入后，持有环境槽位更新 dev，核查实际制品、/health、/ready 和相关业务行为。restart 不证明新代码部署；模板/提示词 Markdown 不能按普通文档跳过部署。
  • 使用共享 dev 的长 E2E 持有环境槽位直到结束；仅在切换到独立固定环境后才可提前释放。失败或未知结果先核对运行态、记录恢复，不能冒充 PASS 或盲目重复执行。
  • CURRENT 槽位字段仍为 holder | phase | since | scope | queue；生产/test 晋升独立授权，dev 任务不得顺手操作 all。

6.4 收口与清理

  • 分别报告已提交、已合入 dev、已部署、已验收、已清理、已推送；文档合入可注明 deployment=not_required。
  • 清理前核对：任务提交是 dev 的祖先、所需验收通过、证据持久化、无 tracked/untracked/唯一 ignored 遗留文件、无 Agent/进程或其他任务使用、路径与分支一致且不属保护项。
  • 使用普通 git worktree remove 和 git branch -d；拒绝时保留并记录 cleanup_pending，不升级到 --force / -D，不批量清空 .worktrees。
  • 未合入或待恢复任务保留 worktree 与 handoff；部署失败按兼容性恢复/前滚，不自动回滚数据库或硬重置 dev。

6.5 共享文档

  • CURRENT 只列 1–3 个焦点；机器状态与 Git 现场优先，CURRENT 是带日期的协作快照。
  • 实现者在任务文记录状态和 FEATURE-MATRIX 变更意图，由集成者串行汇总；保留其他任务、槽位与历史证据。
  • 规范生效与自动化实现分别记录；机器锁服务、队列、脚本守卫和权限沙箱未验收前不得宣称已自动强制。

6.6 Herdr 角色、自动审批与备援

  • 本仓库 Herdr 角色、任务泳道、额度保护和备援顺序以 Herdr Agent roster 为准。
  • Herdr 实例统一通过 scripts/herdr-agent-start.sh 启动；自动派发使用 scripts/herdr-agent-dispatch.sh。
  • 自动审批只消除客户端逐条确认，不扩大任务授权；分支、worktree、mutex、集成槽和破坏性操作红线继续生效。
  • 自动接管仅允许发生在未开始写入且明确的额度、认证、客户端或启动失败。timeout / unknown 不证明任务未执行，必须停止重复投递并先检查 pane 与 handoff。
  • 名称 context_pi / “Herdr PI”专指协作终端内的 PI CLI；产品容器中的执行器统一称“产品 PI Agent Runner”，两者禁止混称或互相代替验收。
  • 未进入 roster 的新模型（包括尚未接入的 Devin）默认 standby，通过一次只读任务和一次隔离 worktree 写任务验证后再进入路由。

7. 文档生命周期

audit（问题）→ remediation（方案）→ ops/short-term（任务）
  → test-reports（验收）→ archive/（关闭证据）

会话结束：session-close-checklist.md

8. Git 与提交

  • 遵循 Conventional Commits：feat / fix / refactor / test / docs / chore / ci
  • 原子提交：一个逻辑变更一批；提交发生在 feature/* 或 fix/* 上，不在三大主干
  • 合回 dev：占槽验证 --no-ff 合并候选，dev 接收已验证节点（见 §6.3）；只在任务分支直接开发提交
  • 晋升：dev → test（rc tag）→ main（release tag）；仅在规划的环境合并时动 test/main
  • 用户未要求：不擅自 push
  • 用户已要求 push/同步远端：必须自主完成
  • 禁止：在 dev/test/main 上直接开发 commit；在 git config 写入 token；硬重置/强推/删库仅在用户明确授权时

9. Secrets 与远端推送（自主，禁止索要）

查找顺序

  1. ${HOME}/.secrets/（如 gitea）
  2. PROJECT.md 与 push 脚本（scripts/git-push-dev.sh）

禁止

  • 向用户索要 token
  • 在聊天/文档/commit 中展示 secret
  • 把 token 写入仓库或 .env 并提交

缺失时

在 ops/handoff 记 blocker（路径 + 缺字段）；仍不索要 secret 内容。

10. 安全与合规红线

  • 不提交 .env、密钥、凭证、生产数据倾倒
  • 破坏性命令仅在用户明确授权时
  • XSS/注入等修复优先于功能扩展

11. 计划 / 实现 / 验证

  1. 大改动：先 short-term 范围；范围外记 long-term
  2. 实现：按 PROJECT 测试命令验证
  3. 完成定义：checklist 勾选须有证据链接

12. 沟通

  • 对用户：简洁、中文
  • 指向文件路径，不复述长篇规则
  • 需要决策时 一次只问 1–2 个关键问题

13. 工具入口（薄转发）

工具 入口
Cursor .cursor/rules/* + 本文件
Claude Code CLAUDE.md
Codex CODEX.md
Gemini GEMINI.md
Antigravity ANTIGRAVITY.md
Kimi KIMI.md

均转发至本文件启动链。

14. 模板索引

类型 路径
短期任务 .doc/ops/templates/short-term-task.md
长期任务 .doc/ops/templates/long-term-task.md
Checklist .doc/ops/templates/checklist.md
交接 .doc/ops/templates/handoff.md
调研 .doc/ops/templates/research-note.md
审计笔记 .doc/ops/templates/audit-note.md
整改方案 .doc/ops/templates/remediation-plan.md
完成度行 .doc/ops/templates/feature-matrix-row.md
会话结束 .doc/ops/templates/session-close-checklist.md

本仓库差异化约定见 PROJECT.md。

Reference in New Issue View Git Blame Copy Permalink