Files

T

weichenandCursor 0d10c9adfe docs(ops): 建立通用 AGENTS 手册与本仓 PROJECT/CLAUDE 入口

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-09-13 02:50:23 +00:00

6.4 KiB

Raw Blame History

Agent 工作手册（通用）

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

1. 目的与适用范围

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

2. 启动协议（Session Bootstrap）

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

本文件 AGENTS.md（通用工作方式）
PROJECT.md（本仓库地图与约定）
.doc/ops/CURRENT.md（当前焦点、阻塞、下一步）
相关 short-term 任务 / handoff（若存在）
发布/审计类任务：再读 PROJECT 指向的 gap-matrix 等 SSOT

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

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

时机	必须动作
任务开始	在 `short-term/` 或 `long-term/` 新建或更新条目（复制 templates）
里程碑	更新任务文 `status` 与 `CURRENT.md`
调研/审计	写入 `research/` 或任务文「证据」段
验收	写 test-report（路径见 PROJECT），回链到 checklist
会话结束/切换 Agent	写或更新 `handoffs/`
提交	文档变更与代码同批或紧随 `docs(...)` 提交

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

current vs historical：完成项标 done 或移入归档；不删除证据。

4. 活文档区约定

默认路径：.doc/ops/（可由 PROJECT 覆盖）

.doc/ops/
  README.md           # 本区用法
  CURRENT.md          # 一页纸：当前焦点（会话必读）
  short-term/         # 本迭代可关闭的任务
  long-term/          # 跨迭代 backlog
  checklists/         # 可勾选验收清单
  handoffs/           # 会话交接
  research/           # 调研笔记实例
  templates/          # 新建条目时复制

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

5. 文档类型与何时使用

短期任务（short-term）

何时：本迭代可关闭的具体工作
必含：目标、范围、非目标、步骤、验收标准、相关链接
模板：.doc/ops/templates/short-term-task.md

长期任务（long-term）

何时：跨迭代 backlog、架构债、未排期改进
必含：动机、成功标准、依赖、暂不启动原因
模板：.doc/ops/templates/long-term-task.md

Checklist（checklists）

何时：可勾选验收；与短任务 1:1 或 1:N
必含：每项 [ ] / [x] + 证据链接（commit、报告、命令输出）
模板：.doc/ops/templates/checklist.md

调研笔记（research）

何时：只读调查、审计复核、根因分析
必含：结论、证据路径、开放问题、置信度
模板：.doc/ops/templates/research-note.md

交接（handoffs）

何时：会话结束、切换 Agent、长时间阻塞
必含：目标、已完成、未完成、关键文件、如何验证、风险
模板：.doc/ops/templates/handoff.md

报告（test-reports）

路径由 PROJECT.md 指定（本仓为 .doc/test-reports/）
原则：真实控制台/日志取样；禁止 stub 冒充最终验收
在任务文与 CURRENT.md 中用相对链接引用

6. 多 Agent 协作

单一焦点：CURRENT.md 只列 1–3 个当前焦点
并行任务：在 CURRENT 列出 owner/agent 标识与互斥资源（分支、文件、环境）
不覆盖：不覆盖他人未合并工作区；发现冲突先写 handoff/blocker
交接优先：口头转述不可代替 handoff 文件

7. Git 与提交

遵循 Conventional Commits：feat / fix / refactor / test / docs / chore / ci
原子提交：一个逻辑变更一批；便于 review 与回滚
用户未要求：不擅自 push、不 force push 保护分支
用户已要求 push/同步远端：必须自主完成，不得把「请你去点推送」推回用户
禁止：在 git config 写入 token；硬重置/强推/删库仅在用户明确授权时

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

查找顺序

${HOME}/.secrets/ 下与远端相关的文件（如 gitea、github）
本仓 PROJECT.md 与 push 脚本（如 scripts/git-push-dev.sh）中的字段说明

常见字段（格式因宿主而异）

- ACCESS_TOKEN=<token>
- URL_PREFIX=<host-without-scheme>

执行方式

优先调用本仓封装脚本（若存在）
或自行读取 secrets 文件构造 push URL（不写入 git config）

禁止

向用户索要 token 或要求粘贴凭证
在聊天、文档、commit message 中展示 secret
把 token 写入仓库或 .env 并提交

缺失时

在 ops 任务/handoff 记录 blocker：文件路径 + 缺字段名
提示用户在本机补齐该文件后重试
仍不索要 secret 内容

9. 安全与合规红线

不提交 .env、密钥、凭证、生产数据倾倒
不做未授权访问或攻击性利用（本地修复与加固除外）
破坏性命令（git reset --hard、push --force、DROP DATABASE）仅在用户明确授权时
XSS/注入等修复优先于功能扩展

10. 计划 / 实现 / 验证

大改动：先对齐计划或 short-term 范围；范围外记 long-term
实现：按 PROJECT 测试命令验证；失败信息写入任务/报告
完成定义：写进 checklist；勾选须有证据链接（非口头「已完成」）

11. 沟通

对用户：简洁、中文（若 PROJECT 未另规定）
不复述长篇规则；指向文件路径
需要决策时 一次只问 1–2 个关键问题
长输出先给结论，再展开细节

12. 模板索引

新建任何 ops 条目前，先复制对应模板：

类型	模板路径
短期任务	`.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`

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

6.4 KiB Raw Blame History Unescape Escape