# Agent 工作手册（通用）

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

---

## 1. 目的与适用范围

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

---

## 2. 启动协议（Session Bootstrap）

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

1. **本文件** `AGENTS.md`
2. **[PROJECT.md](./PROJECT.md)**（本仓库地图与约定）
3. **[`.doc/README.md`](./.doc/README.md)**（文档 taxonomy）
4. **[`.doc/ops/CURRENT.md`](./.doc/ops/CURRENT.md)**（焦点、并行认领、集成槽位）
5. **[`.doc/status/FEATURE-MATRIX.md`](./.doc/status/FEATURE-MATRIX.md)**（模块完成度）
6. 创建任务、合入、部署、清理前：读 [worktree 工作规范](./.doc/ops/2026-09-21-agent-worktree-workflow.md)（含自动化未落地时的操作方法）
7. 相关 **short-term** / **handoff** / **audit** / **remediation**
8. 发布/审计类任务：[`remediation/gap-matrix.md`](./.doc/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](./.doc/ops/templates/session-close-checklist.md) |
| 提交 | 文档变更与代码同批或紧随 `docs(...)` 提交 |

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

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

---

## 4. 文档 taxonomy

默认路径：`.doc/`（详见 [`.doc/README.md`](./.doc/README.md)）

```text
.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](./.doc/ops/templates/audit-note.md) |
| 整改方案 | `remediation/` | [remediation-plan.md](./.doc/ops/templates/remediation-plan.md) |
| 短期任务 | `ops/short-term/` | [short-term-task.md](./.doc/ops/templates/short-term-task.md) |
| 长期 backlog | `ops/long-term/` | [long-term-task.md](./.doc/ops/templates/long-term-task.md) |
| Checklist | `ops/checklists/` | [checklist.md](./.doc/ops/templates/checklist.md) |
| 交接 | `ops/handoffs/` | [handoff.md](./.doc/ops/templates/handoff.md) |
| 调研 | `ops/research/` | [research-note.md](./.doc/ops/templates/research-note.md) |
| 模块完成度 | `status/FEATURE-MATRIX.md` | [feature-matrix-row.md](./.doc/ops/templates/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`**；按 [操作规范](./.doc/ops/2026-09-21-agent-worktree-workflow.md) 使用带显式起点的 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](./.doc/ops/2026-09-13-herdr-agent-roster.md) 为准。
- Herdr 实例统一通过 [`scripts/herdr-agent-start.sh`](./scripts/herdr-agent-start.sh) 启动；自动派发使用 [`scripts/herdr-agent-dispatch.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. 文档生命周期

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

会话结束：[session-close-checklist.md](./.doc/ops/templates/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](./CLAUDE.md) |
| Codex | [CODEX.md](./CODEX.md) |
| Gemini | [GEMINI.md](./GEMINI.md) |
| Antigravity | [ANTIGRAVITY.md](./ANTIGRAVITY.md) |
| Kimi | [KIMI.md](./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](./PROJECT.md)。**