agent-handoff

Agent 交接 — 引导程序与管理器

此技能用于引导并维护 .ai/ 共享上下文目录，让 AI Agent（Claude、Codex、Gemini、Cursor、Windsurf、OpenCode、Copilot 等）之间能够无缝交接。

始终启用的读写行为由安装过程中注入各 Agent 配置文件（CLAUDE.md、codex.md、.cursorrules 等）的代码片段处理。此技能负责更复杂的操作：首次运行引导、过时检测和项目扫描。

文件格式模板见 references/templates.md。 实际示例见 references/examples.md。

---

此技能的触发条件

• 用户说“agent handoff”“handoff”“bootstrap”“initialize”“set up handoff”或“set up agent context”
• 用户说“continue”“resume”“keep going”或“what was the last agent doing”
• 任何核心 .ai/ 文件缺失、为空或仍包含安装程序占位内容： .ai/PROJECT.md、.ai/PATHS.md、.ai/PLAN.md、.ai/conversations/HANDOFF.md
• HANDOFF.md 已过时（距上次更新超过 7 天）
• 用户询问会话文件、缺少交接写入，或其他 Agent 未调用交接流程
• 用户明确调用 /agent-handoff

---

首次运行引导

如果任何必需文件缺失、为空或仅包含占位内容，请运行完整引导：

• .ai/PROJECT.md
• .ai/PATHS.md
• .ai/PLAN.md
• .ai/conversations/HANDOFF.md

占位内容示例包括 Last updated: —、(empty)、“created (empty, will be populated on first agent run)”或仅包含标题的文件。

步骤 1：创建目录结构

mkdir -p .ai/conversations/decisions .ai/conversations/sessions
mkdir -p ".ai/conversations/sessions/$(date +%F)"

步骤 2：检测项目类型和技术栈

读取所有现有的包清单文件（多语言项目可能有多个）：

• composer.json — PHP（Laravel、Symfony 等）
• package.json — Node.js / 前端（Next.js、Nuxt、React、Vue、Angular 等）
• Gemfile — Ruby（Rails、Sinatra 等）
• requirements.txt / pyproject.toml / Pipfile — Python（Django、Flask、FastAPI 等）
• go.mod — Go
• Cargo.toml — Rust
• pom.xml / build.gradle — Java / Kotlin
• *.csproj / *.sln — .NET

读取所有现有的 Agent / 规范配置：

• CLAUDE.md、AGENTS.md、.cursorrules、.windsurfrules、codex.md、GEMINI.md
• README.md、CONTRIBUTING.md
• .editorconfig、Lint 配置（.prettierrc、eslint.config.*、phpcs.xml 等）

读取环境提示：

• .env.example — 预期的环境变量
• docker-compose.yml / Dockerfile — 容器化设置
• Makefile / justfile — 常用命令

步骤 3：发现文档

扫描以下位置，查找文档文件：

Root:        *.md files (README, CHANGELOG, CONTRIBUTING, ARCHITECTURE, etc.)
Docs:        docs/  documentation/  wiki/  guides/  .github/
Specs:       specs/  spec/  plans/  rfcs/  adrs/  design/  proposals/
API:         docs/api/  api-docs/
             openapi.yaml  openapi.json  swagger.json  swagger.yaml
             *.postman_collection.json (up to 3 levels deep)
             insomnia*.json  insomnia*.yaml
Nested:      docs/archive/  docs/plans/  any docs/ subdirectory with markdown

对于找到的每个位置：

find {dir} -maxdepth 3 -type f \( -name "*.md" -o -name "*.pdf" -o -name "*.postman_collection.json" -o -name "openapi.*" -o -name "swagger.*" \)

阅读标题或前 10 行并进行分类：

类别	示例	优先级
需求	TRD、PRD、BRD	HIGH — 实施前阅读
架构	系统设计、ADR	HIGH
实施计划	路线图、阶段规划文档	HIGH
项目概览	概览、项目简介	HIGH
运维指南	用户指南、运行手册	MEDIUM
API 文档	集成指南、OpenAPI	MEDIUM
功能规格	单项功能规格、RFC	ON-DEMAND
已归档	archive/ 中的内容或旧版本	LOW

**版本检测：**如果存在多个版本（例如 TRD-v3、TRD-v4、TRD-v5），根据最高版本号或最新日期确定当前版本。在“参考文档（当前）”下仅列出当前版本。较旧版本归入“已归档”。

步骤 4：检测规格 / 计划目录模式

如果存在 specs/、rfcs/、adrs/ 或类似目录：

1. 列出所有子目录
2. 选取一个代表性目录并列出其内容
3. 记录检测到的模式（每个条目包含哪些文件）
4. 为所有条目列出一行描述
5. 确认哪些处于进行中、哪些已完成（检查 git 历史或任务复选框）

如果没有正式的规格管理系统，请在可判断的情况下说明项目如何跟踪工作（GitHub Issues、Jira、非正式方式等）。

步骤 5：生成上下文文件

使用 references/templates.md 中的模板，生成：

• .ai/PROJECT.md — 根据检测到的技术栈、架构和关键文档生成
• .ai/PATHS.md — 根据发现的文件和文档生成
• .ai/PLAN.md — 根据当前工作（Git 分支、近期提交、规格状态）生成
• .ai/conversations/HANDOFF.md — 初始状态，并附上“系统已初始化”说明
• .ai/conversations/LOG.md — 仅包含标题

所有日期均使用本地系统的实际时间。在类 Unix 系统上，使用以下命令获取：

date '+%Y-%m-%d %H:%M %Z'
date '+%Y-%m-%d/%H%M%S'

创建新的日志或会话记录时，绝不要复制旧项目文档、模型记忆或先前交接记录中的日期。

步骤 6：将始终生效的片段注入 Agent 配置文件

除非 Agent 会实际读取 .ai/ 文件，否则这些文件毫无用处。此步骤确保每个 Agent 的配置文件都包含始终生效的片段，以驱动启动时读取、任务完成后写入的行为。

从 inject.md 中读取片段（它与此 SKILL.md 文件位于同一目录 — 检查 .claude/skills/agent-handoff/inject.md 或 .agents/skills/agent-handoff/inject.md）。

对于下方列出的每个 Agent 配置文件，检查其中是否已包含标记 ## Agent Handoff (always active)。如果没有，则追加完整片段。 如果已包含，则跳过。

Agent	配置文件	注入时机
Claude Code	CLAUDE.md	始终注入 — 如果文件不存在，则创建
Codex (OpenAI)	codex.md	始终注入 — 如果文件不存在，则创建
Multi-agent / Antigravity	AGENTS.md	始终注入 — 如果文件不存在，则创建
Cursor	.cursorrules	仅当文件或 .cursor/ 目录存在时
Windsurf	.windsurfrules	仅当文件存在时
Gemini CLI / older Antigravity	GEMINI.md	仅当文件或 .gemini/ 存在时
OpenCode	.opencode/instructions.md	仅当 .opencode/ 目录存在时
GitHub Copilot	.github/copilot-instructions.md	仅当 .github/ 目录存在时

如果未找到 inject.md，则改用以下最小备用片段：

## Agent Handoff (always active)


ON EVERY CONVERSATION START, read these files:
1. .ai/PROJECT.md
2. .ai/PATHS.md
3. .ai/PLAN.md
4. .ai/conversations/HANDOFF.md

If any are missing, empty, or placeholder-only, bootstrap/repair .ai/ before work.
Use `date '+%Y-%m-%d %H:%M %Z'` for real local timestamps.

BEFORE YOU FINISH EVERY RESPONSE, complete the handoff write-back:
- Append to .ai/conversations/LOG.md
- Update .ai/conversations/HANDOFF.md if files changed or decisions made
- Create a session file at .ai/conversations/sessions/YYYY-MM-DD/HHMMSS-agent-task-slug.md if files changed or decisions made
- In your final response, mention that handoff was updated or explain why no handoff write was needed
- Identify yourself by agent name in all writes

步骤 7：向用户报告

Agent handoff system initialized.

Discovered: {N} reference documents, {N} feature specs, {N} archived docs.
Key documents: {list top 3}
Active work detected: {feature/branch or "none detected"}
Agent configs updated: {list of files where snippet was injected}
Gaps: {any missing elements like "no test directory found"}

---

过期检测

HANDOFF.md 已过期（距上次更新超过 7 天）：

1. 不要盲目相信交接状态
2. 运行 git log --oneline --since="7 days ago" 检查变更
3. 将 Git 历史与 HANDOFF.md 交叉核对
4. 继续操作前，使用当前状态更新 HANDOFF.md
5. 添加说明：[stale] Handoff was {N} days old. Refreshed from git history.

PATHS.md 引用了已不存在的文件：

1. 删除过期条目
2. 检查文件是否已重命名、移动或被替代
3. 如果找到替代文件，则添加该文件
4. 在 LOG.md 中记录清理操作

---

大小限制

文件	最大行数	执行方式
PROJECT.md	~80	稳定 — 仅在技术栈或架构变化时更新
PATHS.md	~150	将重要性较低的条目合并为目录摘要
PLAN.md	~60	仅跟踪当前功能。已完成的项目 → 用一句话记录
HANDOFF.md	~100	滚动窗口：最多保留 15-20 条近期完成事项。最旧的移至 LOG.md
LOG.md	~500	将 90 天以前的条目归档到 LOG-archive-YYYY.md
会话文件	~80 各	引用提交哈希，而不是重复差异内容

启动读取成本： 合计约 800-1500 个 token（全部 4 个文件）。 每项任务的写入成本： 根据复杂程度约 500-1200 个 token。

---

并发 Agent 安全性

两个 Agent 同时工作时，可能会发生文件冲突。

预防措施：

• HANDOFF.md 的 Active Work 列出每个 Agent 正在处理的事项。 开始前，检查是否有其他 Agent 正在运行。
• 会话文件不会冲突 — 每个 Agent 都写入自己的带时间戳文件。
• LOG.md 仅追加 — 冲突很容易解决（保留两条记录）。

如果 HANDOFF.md 中发生合并冲突：

1. 保留两个 Agent 的 Active Work 条目
2. 按时间顺序合并 Recent Completions
3. 合并所有 Key Context 条目

---

会话文件协议

每当 Agent 修改文件、做出决定、开展未来的 Agent 可能需要了解的调查，或接手另一位 Agent 正在进行的工作时，都必须创建会话文件。

1. 阅读 4 个启动文件。
2. 从环境中获取真实的本地时间。
3. 创建日期目录： mkdir -p .ai/conversations/sessions/$(date +%F)。
4. 使用以下文件名： .ai/conversations/sessions/YYYY-MM-DD/HHMMSS-agent-task-slug.md。
5. 文件应简短、客观。链接到变更文件、文档、提交、测试和阻塞事项，不要粘贴大段差异。
6. 在 HANDOFF.md 的 Active Work 或 Recent Completions 中引用会话文件。
7. 在 LOG.md 中追加对应条目。
8. 在给用户的最终回复中说明已更新交接记录。如果无需写入，请说明原因。

如果 Agent 写入了 LOG.md/HANDOFF.md，却没有为涉及文件变更的任务创建会话文件，则交接记录不完整，下一位 Agent 应根据现有证据创建补录会话文件予以修复。

---

Monorepo 项目

• 将 .ai/ 放在仓库根目录，而不是单个包内
• PATHS.md 应列出所有包/服务及其路径
• PLAN.md 可跟踪跨包工作——使用包前缀
• 会话文件应注明修改了哪些包

---

规则

1. 始终先阅读再开始工作。 在对话开始时阅读 4 个上下文文件。没有例外。
2. 始终在工作后写入。 即使只是问答也要写入——今天回答的问题会成为明天的上下文。
3. LOG.md 应简洁。 每条记录 3-5 行。完整详情写入会话文件。
4. 遵守大小限制。 LOG.md 超过约 500 行时应归档。
5. 记录重要决策。 架构/设计选择 → decisions/ 目录。
6. 不要重复记录 Git 历史。 引用提交哈希，而不是差异。
7. 使用真实时间戳。 绝不使用占位符。
8. 为每条 LOG.md 记录添加标签。 标签便于检索。
9. 保持 PATHS.md 准确。 新增文件或文档时 → 更新 PATHS.md。
10. 取得进展时更新 PLAN.md。 标记已完成任务、添加阻塞事项并注明 Agent。
11. 渐进式披露。 HANDOFF.md → 会话文件 → 源文件。
12. 注明身份。 所有写入内容都要包含 Agent 名称。
13. LOG.md 只追加。 绝不删除记录。
14. 恢复工作时进行验证。 继续另一位 Agent 的工作前，检查相关文件是否存在。
15. 实现前先阅读文档。 在 PATHS.md 中查找相关规范/计划。
16. 立即索引新文档。 不要留给下一位 Agent 处理。
17. 以当前文档为准。 绝不要将已归档文档作为权威依据。
18. 记录参考来源。 在会话文件的 References 部分列出查阅过的文档。