267 lines
9.4 KiB
Markdown
267 lines
9.4 KiB
Markdown
# 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. 相关 **short-term** / **handoff** / **audit** / **remediation**
|
||
7. 发布/审计类任务：[`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 并行认领（编码阶段）
|
||
|
||
任务开始前在 CURRENT「并行认领」表登记：
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| owner | 工具 + 标识 |
|
||
| task | short-term 文件名 |
|
||
| branch | `feature/*` 或 `fix/*` |
|
||
| worktree | 路径或 `-` |
|
||
| mutex | 模块名（见 FEATURE-MATRIX） |
|
||
| status | `in_progress` / `blocked` / `done` |
|
||
|
||
**同一 mutex 同时仅一个 `in_progress`**。冲突 → 写 handoff blocker，禁止覆盖他人未合并改动。
|
||
|
||
### 6.2 分支与 Worktree（策略 A：一律从 dev 开分支）
|
||
|
||
> **禁止**在 `dev` / `test` / `main` 三大主干上直接 `git commit`（含代码、配置、文档）。
|
||
> `dev` 仅作合入点；`test`/`main` 仅作环境晋升合入，禁止开发。
|
||
|
||
**任务开始（先于改码）：**
|
||
|
||
1. 更新本地 `dev`：`git checkout dev && git pull`（若已配置远端）
|
||
2. 从 `dev` 创建分支：`feature/<slug>`（新能力）或 `fix/<slug>`（缺陷）；slug 与 short-term 任务名对齐
|
||
3. 多 Agent 并行：用 `./scripts/agent-worktree.sh create feature/<slug>`（worktree 内编码）
|
||
4. 单 Agent：可在主仓 `git checkout -b feature/<slug>`，**不得**留在 `dev` 上改码提交
|
||
|
||
**合回 dev（占集成槽位，见 §6.3）：**
|
||
|
||
```bash
|
||
git checkout dev
|
||
git merge --no-ff feature/<slug> -m "merge: feature/<slug>"
|
||
# 冒烟通过后
|
||
git branch -d feature/<slug> # 或 agent-worktree.sh remove
|
||
```
|
||
|
||
| 允许 | 禁止 |
|
||
|------|------|
|
||
| 在 `feature/*` / `fix/*` 上 commit | 在 `dev` / `test` / `main` 上 commit |
|
||
| worktree 内 `go test -short ./...` | worktree 内 `env-service.sh * start/stop/restart` |
|
||
| 占槽后在主仓 merge 入 `dev` | 多人直推同一 `dev` 工作区抢改 |
|
||
| 连主仓已起服务 `:8080` | 各 worktree 各起 docker |
|
||
|
||
脚本：`./scripts/agent-worktree.sh create|list|remove`
|
||
|
||
### 6.3 集成槽位（合入 dev + 容器验证）
|
||
|
||
> **编码与 worktree 单测可并行；合入 dev + 共享容器验证必须串行。**
|
||
|
||
Agent A 占槽 merge + 冒烟期间，Agent B **不得** merge dev 或动共享 docker；B 可继续 worktree 编码，并写入 queue 等待。
|
||
|
||
CURRENT「集成槽位」：`holder` | `phase`（idle/merging/smoke/e2e）| `since` | `scope` | `queue`
|
||
|
||
**释放**：冒烟 PASS（或 FAIL+handoff）+ 文档同步 + holder=idle。长 E2E 优先 smoke 释放，E2E 结果后补报告。
|
||
|
||
**默认冒烟（holder 在主仓执行）**：
|
||
|
||
```bash
|
||
go vet ./...
|
||
go test -short ./...
|
||
./scripts/env-service.sh dev rebuild
|
||
curl -sf http://127.0.0.1:8080/health
|
||
```
|
||
|
||
### 6.4 共享文档
|
||
|
||
`CURRENT.md` / `FEATURE-MATRIX.md` 由认领方或合并者更新；冲突时保留双方认领行再收敛。
|
||
|
||
### 6.5 协作纪律
|
||
|
||
- **单一焦点**：CURRENT 只列 1–3 个焦点
|
||
- **不覆盖**：发现冲突先 handoff/blocker
|
||
- **交接优先**：口头转述不可代替 handoff 文件
|
||
|
||
---
|
||
|
||
## 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**：占集成槽位后 `merge --no-ff`（见 §6.2、§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)。**
|