project-onboard

项目接入

一项可将 AI Agent 接入任意项目的技能，通过生成结构化、按任务路由的上下文文件来实现。与生成扁平 Agent 文件的 /init 不同，此技能会创建渐进式披露系统，让 Agent 仅阅读当前任务所需的内容，从而节省 token，并避免重复探索项目。

调用

/project-onboard                     First run: full onboard. Re-run: refresh + audit.
/project-onboard --quick             Phase 1+2 only (skip audit & interview)
/project-onboard Thai                Full onboard, confirm output language first

不要创建或记录单独的更新或审计命令。/project-onboard 是唯一入口；再次运行时，它会刷新现有上下文并自动重新执行审计。 将普通的“onboard”视为自然语言请求，按 project-onboard 的行为执行；不要创建、记录或提及 /onboard 斜杠命令。

从这里开始：选择运行模式

执行任何阶段之前，先判断这是首次接入还是重新运行。即使用户只说 /project-onboard，也要进行判断，因为同一命令既处理首次接入，也处理重新运行。

检查是否存在已生成的上下文：

• .context/onboard-meta.json
• AGENTS.md 或 CLAUDE.md
• .context/features/audit-meta.json

使用以下决策表：

情况	运行模式
不存在 .context/onboard-meta.json，且不存在已生成的指令文件	首次接入
不存在 .context/onboard-meta.json，但存在 AGENTS.md 或 CLAUDE.md，且其中没有 project-onboard 标记	首次接入，并遵循现有指令文件策略
存在 .context/onboard-meta.json，且用户说 /project-onboard、“再次 onboard”、“重新运行”、“更新”或“刷新”	重新运行 project-onboard：刷新 + 审计
存在现有上下文，但元数据缺失或无效	恢复性重新运行：完整刷新 + 审计，保留现有文件
用户在新仓库中请求 /project-onboard --quick	首次快速运行：仅执行 Phase 1+2
用户在已接入的仓库中请求 /project-onboard --quick	快速重新运行：仅刷新已生成的上下文；跳过审计和访谈

已生成的 project-onboard 标记包括 ``、.context/onboard-meta.json，或指向 .context/ 的任务路由。如果指令文件存在但不包含这些标记，则将其视为需要保留并合并的用户编写内容，而不是 project-onboard 已运行的证明。

首次接入

执行 Phase 1 和 Phase 2。然后询问是否执行 Phase 3 和 Phase 4，除非用户请求了 --quick。

重新运行 project-onboard

刷新已生成的上下文，然后重新执行审计。不要询问是否进行审计；重新运行 onboard 本身就表示要让已生成的上下文保持最新。这是同一个 /project-onboard 命令的内部行为，不是单独的更新或审计命令。

重新运行目标：

1. 刷新过时或已变更的上下文文件。
2. 对发生变更的区域重新执行 8 类别审计；如果无法可靠地检测变更，则完整审计。
3. 更新 .context/features/_feature-map.md 和审计元数据。
4. 当路由、API、数据、身份验证、任务、集成、测试、警告或工作流发生变化时，更新规范指令文件中的任务路由。
5. 保留通过访谈生成的文件和用户编写的指令内容。仅更新 project-onboard 自动生成的部分，除非用户明确要求修改用户编写的内容。
6. 更新 .context/onboard-meta.json 中的 last_update、last_audit、git_commit、已完成阶段、检测到的类别和已缓存文档状态。

如果仓库没有 Git 历史、存储的提交记录缺失，或 diff 失败，则回退为保守的完整刷新：执行 Phase 1、Phase 2 上下文文件刷新和 Phase 3。保留访谈回答和现有用户编写的部分。

语言支持

如果用户在命令后附加语言名称（例如，/project-onboard Thai /project-onboard Japanese），请在继续之前确认语言：

"You requested output in Thai. This will generate all context files
and agent instruction files in Thai. Confirm? (yes/no)"

如果用户确认，请用该语言编写所有输出文件——AGENTS.md、 CLAUDE.md 垫片、上下文文件、功能映射，所有文件均如此。SKILL.md 中的说明仍保持英文，但生成的输出应遵循用户选择的语言。

如果未指定，默认语言为英语。

工作原理

此技能分为 4 个阶段。每个阶段都基于前一个阶段展开。 Agent 在每个阶段都会掌握更多信息，因此后续阶段会更智能。

Phase 1: DISCOVER .......... auto-detect stack + research docs
Phase 2: GENERATE .......... create AGENTS.md + CLAUDE.md shim + context files
Phase 3: FEATURE AUDIT ..... map Page → API → DB → Feature (optional)
Phase 4: INTERVIEW ......... ask the developer (knows everything now)

首次运行时，第 3 和第 4 阶段为可选阶段。再次运行时，除非用户请求 --quick，否则会自动执行第 3 阶段。首次运行时，在第 2 阶段结束后，询问用户：

• “要我审查现有功能吗？（映射页面、端点、数据库）”
• “要我通过访谈了解业务背景吗？”

如果用户运行 /project-onboard --quick，则跳过第 3 和第 4 阶段。

再次运行时，技能应保持简洁直接：先更新生成的上下文和审查输出， 然后总结变更内容。仅当规范指令文件的选择不明确，或需要决定如何保留用户编写的内容时，才提问。

---

第 1 阶段：发现

分为两个子阶段。在此阶段不要询问用户任何问题。

第 1a 阶段：检测

读取项目文件，识别技术栈和工具。 不要递归使用 find 或 ls。仅读取已知的特定文件。

检查以下文件（如果不存在则跳过）：

包管理器和技术栈：

• package.json → Node.js 生态系统、框架、依赖项、脚本
• pubspec.yaml → Flutter/Dart
• go.mod → Go
• requirements.txt / pyproject.toml / Pipfile → Python
• Cargo.toml → Rust
• composer.json → PHP
• Gemfile → Ruby

移动端：

• package.json 依赖项中的 react-native → React Native
• app.json / app.config.js → Expo
• pubspec.yaml 依赖项中的 flutter → Flutter

状态管理：

• 依赖项中的 @reduxjs/toolkit / zustand / jotai / @tanstack/react-query
• pubspec.yaml 中的 riverpod / bloc / provider

后台任务：

• 依赖项中的 bullmq / bull / celery / sidekiq
• 队列处理器文件

国际化：

• 语言文件（en.json、th.json 等）
• 依赖项中的国际化库（next-intl、react-i18next、flutter_localizations）

配置：

• tsconfig.json → TypeScript 设置
• .eslintrc* / biome.json / .prettierrc → 代码检查/格式化
• docker-compose.yml / Dockerfile → 容器化
• vercel.json / netlify.toml / fly.toml → 部署目标
• .env.example → 环境变量（绝不读取 .env）

数据库：

• prisma/schema.prisma → Prisma 架构
• drizzle.config.ts → Drizzle ORM
• knexfile.* / ormconfig.* → 其他 ORM
• migrations/ 或 db/migrate/ → 检查迁移工具

CI/CD 和工作流：

• .github/workflows/ → GitHub Actions
• .gitlab-ci.yml → GitLab CI
• .husky/ → git 钩子

测试：

• jest.config* / vitest.config* / playwright.config* / cypress.config*
• 统计测试文件数量：有多少个 *.test.* 或 *.spec.* 文件

现有 AI 上下文：

• AGENTS.md → 首选的规范 Agent 指令；保留，稍后合并
• CLAUDE.md → 现有 Claude Code 指令；迁移前询问用户
• .cursor/rules/ → 导入约定
• .github/copilot-instructions.md → 现有 Copilot 规则

文档：

• README.md → 项目描述、设置
• CONTRIBUTING.md → 团队约定
• CHANGELOG.md → 最近变更、当前版本
• docs/ → 架构文档

Phase 1b：调研

使用 Phase 1a 中的信息开展有针对性的调研。

1. 项目文档 — 阅读仓库中现有的内容

通读 README.md。提取：项目目的、设置说明、架构备注。如果存在 CONTRIBUTING.md 或 docs/，也要阅读。

2. 技术栈文档 — 通过 Context7 获取最新文档（按条件执行）

如果 .context/onboard-meta.json 存在，则阅读该文件。对于每个主要依赖项：

• 如果版本自上次 onboard 以来发生变化 → 获取最新文档
• 如果文档已超过 7 天 → 获取最新文档
• 如果文档是最新的且版本未变 → 跳过，使用缓存

获取文档时，针对检测到的特定版本查询 Context7。 重点关注：约定、重大变更、迁移指南、最佳实践。

将结果保存到 .context/stack-docs/{lib}-{version}.md

3. 技能 — 搜索相关技能

根据检测到的技术栈，搜索可用技能：

• 如果 CLI 可用，运行 npx skills search {framework}
• 或记录以下已知来源的推荐：
  • vercel-labs/agent-skills（React、Next.js、部署）
  • VoltAgent/awesome-agent-skills（社区精选集）

将推荐内容留作 Phase 2 输出和 Phase 4 建议。

4. 生态系统 — 核实实际工具

阅读 package.json 脚本，了解实际的构建、测试和开发命令。 阅读 CI 配置，了解实际的流水线步骤。 阅读 tsconfig/eslint，了解实际的代码约定。 不要假设 — 请根据配置文件核实。

---

Phase 2：生成

生成输出文件。阅读 references/output-format.md，了解完整模板和文件结构。

路径规则 — 写入任何文件前请仔细阅读：

• 上下文文件放在 project-root/.context/（顶层点号目录）
• 标准 Agent 指令放在 project-root/AGENTS.md（复数）
• Claude Code 兼容指令放在 project-root/CLAUDE.md
• 唯一的 Claude 命令放在 project-root/.claude/commands/project-onboard.md
• 项目根目录下有两个独立的目录。不要将 .context/ 嵌套在 .claude/ 中。
• 错误：.claude/context/、.claude/.context/、.claude/architecture.md
• 正确：AGENTS.md、CLAUDE.md、.context/architecture.md、.claude/commands/project-onboard.md

创建第一个文件前，请再次确认：你准备写入 .context/ 还是 .claude/context/？ 如果路径中包含 .claude/context 或 .claude/.context，请停止 — 路径错误。将其改为 .context/。

输出结构

project-root/
├── AGENTS.md                          # ≤ 150 lines, canonical task-routed instructions
├── CLAUDE.md                          # Compatibility shim pointing to AGENTS.md, unless user chooses otherwise
├── .context/                          # ⚠️ THIS IS project-root/.context/ — NOT .claude/context/
│   ├── architecture.md                # Directory map + patterns
│   ├── conventions.md                 # Coding standards (from config)
│   ├── workflow.md                    # CI/CD, deploy, branch strategy
│   ├── stack-docs/                    # Cached library docs
│   │   └── {lib}-{version}.md
│   ├── warnings.md                    # Things to watch out for
│   └── onboard-meta.json             # Metadata for reruns
└── .claude/
    ├── commands/
    │   └── project-onboard.md                 # /project-onboard command (single entrypoint)
    └── .claudeignore                  # (if not exists) auto-generated

⚠️ 严重路径警告： .context/ 位于项目根目录 — 与 AGENTS.md 和 CLAUDE.md 同级。 切勿创建 .claude/context/ — 这是错误的。两个目录彼此独立：

• .context/ = onboard 上下文文件（架构、约定、功能等）
• .claude/ = 仅存放 Claude 命令和配置

Agent 指令文件 — 重要规则

优先使用 AGENTS.md（复数）作为标准指令文件。这里采用的约定不是单数形式的 AGENT.md。

标准指令文件不是面向人类的文档，而是供 AI Agent 使用的决策树。

请采用基于任务的路由模式编写：

BEFORE [action] → read [file]
WHEN [situation] → read [file]

不要只列出文件。务必告诉 Agent 何时阅读每个文件。

阅读 references/output-format.md，了解完整的 AGENTS.md 模板和 CLAUDE.md 垫片模板。

现有指令文件策略

在编写 AGENTS.md 或 CLAUDE.md 之前，先检测哪些指令文件 已经存在：

• 如果 AGENTS.md 和 CLAUDE.md 都不存在：
  • 在 AGENTS.md 中创建完整的任务路由内容。
  • 创建一个简短的 CLAUDE.md 垫片，告知 Claude Code 先阅读 AGENTS.md。
• 如果 AGENTS.md 存在，而 CLAUDE.md 不存在：
  • 保留并合并内容到 AGENTS.md。
  • 创建一个简短的 CLAUDE.md 垫片，指向 AGENTS.md。
• 如果 CLAUDE.md 存在，而 AGENTS.md 不存在：
  • 在更改归属前询问用户： "我发现了一个现有的 CLAUDE.md。你希望我将其内容迁移到 AGENTS.md 并把 CLAUDE.md 替换为指针文件，还是保留 CLAUDE.md 作为规范文件，并创建一个指向它的 AGENTS.md 指针文件？"
  • 如果用户选择迁移：读取 CLAUDE.md，将所有用户编写的 内容保留在 AGENTS.md 中，添加生成的任务路由章节，然后将 CLAUDE.md 替换为指向 AGENTS.md 的垫片。
  • 如果用户选择保留 Claude 为规范文件：保留并合并内容到 CLAUDE.md，然后创建一个指向 CLAUDE.md 的 AGENTS.md 垫片。
• 如果 AGENTS.md 和 CLAUDE.md 都存在：
  • 读取两者。
  • 除非 CLAUDE.md 明显包含更新或更完整的用户编写指令，否则 优先将 AGENTS.md 作为规范文件。
  • 如果无法明确选择规范文件，则在合并前询问。
  • 将非规范文件保留为指向规范文件的垫片。

绝不要丢弃用户编写的指令内容。只有在原始内容已迁移到规范文件 或用户明确选择该方向后，垫片才能替换现有文件。

上下文文件——面向 AI 的写作

每个上下文文件都必须以以下内容开头：

1. 何时读取此文件（一行）
2. Agent 应如何使用这些信息
3. 实际内容——简洁、结构清晰、可执行

不要写散文。应编写 Agent 可以执行的结构化数据。

onboard-meta.json

{
  "version": "2.0",
  "last_onboard": "ISO-8601",
  "last_update": "ISO-8601",
  "last_audit": "ISO-8601",
  "git_commit": "hash",
  "previous_git_commit": "hash",
  "language": "en",
  "agent_instructions": {
    "canonical": "AGENTS.md",
    "shim": "CLAUDE.md",
    "shim_direction": "CLAUDE.md -> AGENTS.md"
  },
  "stack": ["nextjs", "prisma", "postgresql"],
  "platforms": {
    "web": true,
    "mobile": false,
    "backend": true
  },
  "categories_detected": [
    "pages-routing",
    "api-middleware",
    "data-layer",
    "auth-security",
    "background-events",
    "integrations-infra"
  ],
  "stack_docs": {
    "next": { "version": "15.1.0", "docs_pulled_at": "ISO-8601" }
  },
  "phases_completed": ["discover", "generate"],
  "interview_done": false,
  "audit_done": false,
  "last_run_mode": "first-onboard | rerun-project-onboard | first-run-quick | rerun-quick | recovery-rerun"
}

与现有指令文件合并

如果规范指令文件已存在：

1. 完整读取
2. 保留所有现有内容
3. 添加缺失的章节（任务路由、上下文引用、警告）
4. 不要覆盖用户编写的内容
5. 使用 `` 标记生成的章节

技能建议

生成文件后，向用户展示可用的技能：

"Detected: Next.js + React + Prisma. Recommended skills:"
  1. vercel-react-best-practices — 40+ React performance rules
  2. web-design-guidelines — accessibility + UX audit
  
"Install with: npx skills add vercel-labs/agent-skills@vercel-react-best-practices"
"Want me to install any of these?"

---

阶段 3：通用审计（首次运行时可选，重新运行时自动执行）

首次引导时，除非用户已要求进行审计，否则先询问再运行："要我审计现有功能吗？我会扫描页面、状态、UI、API、数据、身份验证、作业和集成。"重新运行 project-onboard 时，不要询问；刷新生成的上下文后自动运行审计。

使用 8 个类别扫描代码库。每个类别都会自动检测，并在未发现时自动跳过。阅读 references/universal-audit.md 了解完整的扫描策略，然后阅读 templates/feature-audit-format.md 获取确切的输出模板。

8 个类别

#	类别	输出文件	涵盖内容
1	页面与路由	pages-routing.md	页面、屏幕、导航、深层链接、路由守卫
2	状态与数据获取	state-data.md	存储、切片、提供程序、客户端缓存、数据获取
3	设计系统与 UI	design-system.md	组件、主题、表单、国际化、无障碍功能
4	API 与中间件	api-middleware.md	端点、中间件管道、验证、错误处理
5	数据层	data-layer.md	数据库架构、迁移、缓存、事务、种子数据
6	身份验证与安全	auth-security.md	身份验证、授权、速率限制、CORS、机密信息
7	后台与事件	background-events.md	任务、事件驱动架构、定时任务、服务通信
8	集成与基础设施	integrations-infra.md	外部 API、文件存储、日志记录、配置、健康检查

在 _feature-map.md 中交叉引用所有检测到的类别。 同时识别孤立项：未映射的端点、页面、状态、任务和数据库表。

审计刷新模式

在已完成引导的仓库上重新运行 /project-onboard 时：

1. 如果 .context/features/audit-meta.json 存在，则读取它。
2. 如果 .context/onboard-meta.json 存在，则读取它。
3. 确定变更文件：
   • 如果本次运行中的上下文刷新步骤已生成变更文件， 则复用这些文件。
   • 如果无法获取变更文件，则从 audit-meta.json 中记录的提交进行差异比较；如果不存在，则使用 onboard-meta.json 中的 git_commit；如果仍不存在，则使用 previous_git_commit。
   • 如果没有可靠的提交可用，则运行完整审计。
4. 根据变更文件选择受影响的审计类别。
5. 充分重新扫描受影响的类别，确保交叉引用准确无误。 页面变更可能影响 API 调用方；API 变更可能影响页面和 功能映射；架构、身份验证、任务和集成变更可能影响多个功能部分。
6. 始终根据当前类别输出重新生成 .context/features/_feature-map.md，因为功能映射是跨类别索引。
7. 如果无法有把握地确定受影响的类别，则运行完整的 8 类别审计，而不是保留过时的功能映射。
8. 更新 audit-meta.json，记录已扫描的类别、已跳过的类别、覆盖数量、孤立项数量、last_audit 和所用的 Git 提交。

输出文件

请记住：.context/ 位于项目根目录，而不是 .claude/ 内。

.context/features/
  ├── _feature-map.md           # Cross-reference all categories per feature
  ├── pages-routing.md          # 1: Pages & Routing (web + mobile)
  ├── state-data.md             # 2: State & Data Fetching
  ├── design-system.md          # 3: Design System & UI
  ├── api-middleware.md          # 4: API & Middleware
  ├── data-layer.md             # 5: Data Layer
  ├── auth-security.md          # 6: Auth & Security
  ├── background-events.md      # 7: Background & Events
  ├── integrations-infra.md     # 8: Integrations & Infra
  └── audit-meta.json           # Coverage stats per category

生成后，使用任务路由规则更新规范指令文件：

BEFORE modifying or creating any page, screen, or route:
  → read .context/features/pages-routing.md
  → read .context/features/_feature-map.md

BEFORE modifying app state (stores/slices/providers):
  → read .context/features/state-data.md
  → read .context/features/pages-routing.md (check consumers)

BEFORE modifying UI components, theming, forms, or i18n:
  → read .context/features/design-system.md

BEFORE modifying or creating any API endpoint:
  → read .context/features/api-middleware.md
  → read .context/features/pages-routing.md (check callers)

BEFORE modifying database schema, caching, or migrations:
  → read .context/features/data-layer.md
  → read .context/features/_feature-map.md (check impact)

BEFORE modifying auth, permissions, or security config:
  → read .context/features/auth-security.md

BEFORE modifying background jobs, events, or service communication:
  → read .context/features/background-events.md

BEFORE modifying external integrations, logging, or config:
  → read .context/features/integrations-infra.md

---

第 4 阶段：访谈（可选）

此时，Agent 已扫描并了解整个项目。 问题将根据第 1 至第 3 阶段发现的信息提出。

运行前先询问：“要我问你一些关于 这个项目的问题吗？这有助于我了解代码无法告诉我的信息。”

如果已完成第 3 阶段——简短访谈（3 个问题）

Agent 已经深入了解代码库。只询问代码无法揭示的信息：

1. "[Summary from README + code]. Is this accurate?
    Any business context or domain terms I should know?"

2. "Any conventions, processes, or areas I should NOT touch
    without asking first?"

3. "Anything else you want me to know?"

如果跳过了第 3 阶段——完整访谈（4 组）

第 1 组：业务与领域

1. "What does this project do? Who are the main users?"
2. "Any domain-specific terms I should understand?"
3. "What phase is this project in?
    (MVP / active dev / maintenance / legacy refactor)"

第 2 组：团队与工作流

4. "How many people work on this? Code review process?"
5. "Branch strategy? (trunk-based / gitflow / feature branches)"
6. "Deploy process? (auto/manual, staging environment?)"
7. "Any conventions you want me to always follow?"

第 3 组：代码质量与测试

8. "Want to restructure the code?
    (e.g., extract business logic to service layer)"
    — If Phase 1 found logic in route handlers, mention it specifically.

9. "Do you want TDD? (write tests before implementation)"

10. "Testing strategy?"
    — Unit only
    — Unit + Integration
    — Unit + Integration + E2E
    — No tests yet, want to start

11. "Test framework preference?"
    — Mention what was detected: "Found [vitest/jest], correct?"
    — For E2E: Playwright / Cypress / other?

12. "Coverage target? (none / 60% / 80% / 90%+)"
    — If tests exist, mention current estimated coverage.

第 4 组：AI 行为

13. "Anything that AI agents frequently break in this project?"

14. "Files or folders I should never modify without asking?"

15. "How autonomous should I be?"
    — Conservative: always ask before acting
    — Balanced: act but explain
    — Autonomous: just do it

16. "Anything else I should know?"

自适应问题

问题必须根据发现的内容调整。如果已从第 1 至第 3 阶段获得答案，就不要提出泛泛的问题。

示例——检测到测试：

BAD:  "Do you want to write tests?"
GOOD: "Found Vitest with 23 test files, ~45% coverage.
       Want me to help increase coverage? Add E2E with Playwright?"

示例——路由处理器中包含逻辑：

BAD:  "Want to restructure the code?"
GOOD: "Found business logic directly in route handlers
       (e.g., /api/pipelines has 120 lines of logic).
       Want me to extract it to a service layer?"

访谈输出

将答案保存到上下文文件：

• 业务上下文 → .context/business.md
• 测试策略 → .context/testing-strategy.md
• 更新 warnings.md，记录需要保护的文件／区域
• 更新 workflow.md，记录团队流程信息
• 更新 conventions.md，记录已说明的偏好
• 在规范指令文件的任务路由部分添加新章节

更新 onboard-meta.json：设置 interview_done: true。

---

重新运行项目初始化（/project-onboard）

当用户在已有初始化上下文的仓库中运行 /project-onboard 时，通过同一命令刷新生成的上下文并重新运行审计。不要让用户运行单独的更新或审计命令。

1. 读取 .context/onboard-meta.json
2. 验证 agent_instructions.canonical 中记录的规范指令文件；如果该文件已移动或不存在，则使用现有指令文件策略检测最合适的规范文件。
3. 运行 git diff {last_commit}..HEAD --name-only 查找已更改的文件
   • 使用元数据中的 git_commit 作为 {last_commit}。
   • 如果 git_commit 缺失、无效或不可用，则回退到 previous_git_commit。
   • 如果无法运行 git diff，则执行完整刷新。
   • 如果 diff 为空，仍需检查文档缓存是否为最新，以及审计元数据的时间戳，再决定是否无需更新。
4. 对每个已更改的文件，确定需要更新哪些上下文文件：
   • package.json 已更改 → 重新检测技术栈，检查是否需要刷新文档
   • prisma/schema.prisma 已更改 → 更新 .context/features/data-layer.md + .context/features/_feature-map.md
   • 路由文件已更改 → 更新 .context/features/api-middleware.md + .context/features/_feature-map.md
   • 页面文件已更改 → 更新 .context/features/pages-routing.md + .context/features/_feature-map.md
   • 配置文件已更改 → 更新 conventions.md 或 workflow.md
5. 仅更新受影响的上下文文件；如果任务路由发生变化，则更新 agent_instructions.canonical 中记录的规范指令文件
6. 保留 agent_instructions.shim_direction 中记录的 shim 方向，除非用户要求更改规范文件归属
7. 除非用户请求 /project-onboard --quick，否则在刷新上下文文件后运行 Phase 3 审计刷新模式。
8. 保留通过访谈生成的文件，除非用户要求重新进行访谈：
   • .context/business.md
   • .context/testing-strategy.md
   • 合并到 .context/warnings.md、.context/workflow.md 和 .context/conventions.md 中的访谈部分
9. 使用新的时间戳、previous_git_commit、当前的 git_commit、last_run_mode 以及审计运行时的审计字段更新 onboard-meta.json。替换 git_commit 前，将旧的 git_commit 复制到 previous_git_commit；首次初始化时，将 previous_git_commit 设为 null 或省略该字段。
10. 显示摘要：“根据自上次初始化以来的 Z 个已更改文件，更新了 X 个上下文文件和 Y 个审计文件”

对于完整刷新请求或恢复性重跑：

• 从 Phase 1 重新扫描所有内容。
• 重新生成所有生成的上下文文件。
• 保留访谈答案；除非用户要求重新进行访谈，否则不要再次询问。
• 除非用户请求 /project-onboard --quick，否则运行 Phase 3。

重跑安全规则

• 绝不删除 AGENTS.md、CLAUDE.md 或上下文文件中的用户编写部分。在原位置合并生成的部分。
• 绝不只因代码发生变化就重写访谈答案。
• 重跑时绝不跳过功能映射。如果任何类别发生变化，则重建 _feature-map.md。
• diff 可靠时优先进行有针对性的更新；如果 diff 缺失、含糊不清或可能导致上下文过时，则优先进行完整刷新。
• 重跑时不要询问用户常规的首次运行问题。仅在规范文件归属不明确或业务上下文明确缺失时提问。

---

技术栈文档缓存

Context7 文档缓存在 .context/stack-docs/ 中。 拉取策略：

条件	操作
从未拉取	立即拉取
库版本已更改	立即拉取（可能包含不兼容变更）
版本相同，文档不超过 7 天	跳过，使用缓存
版本相同，文档超过 7 天	拉取最新文档
用户运行 --force-docs	拉取所有内容

---

未来：多 Agent 支持

此技能会生成 AGENTS.md，作为规范的、与 Agent 无关的入口文件，并生成 CLAUDE.md，作为 Claude Code 兼容性垫片。未来版本可能会支持其他封装文件：

Claude Code  → CLAUDE.md shim → AGENTS.md + .context/
Cursor       → .cursor/rules/
Codex        → AGENTS.md + .context/
Copilot      → .github/copilot-instructions.md

.context/ 中的上下文文件采用与 Agent 无关的 Markdown 编写。要支持其他 Agent，只需生成一个指向相同上下文的封装文件。

---

参考文件

生成输出前请先阅读：

• references/output-format.md — AGENTS.md 模板、CLAUDE.md 垫片模板、上下文文件模板
• references/universal-audit.md — 所有 8 个审计类别的完整扫描策略和输出模板
• templates/feature-audit-format.md — 功能审计输出模板