setup-agentic-repository

setup-agentic-repository

你正在搭建一组指令文件，AI Agent 会在每次会话开始时读取这些文件，以了解如何在项目中工作。输出应是一套完整的、针对特定项目的指令树，而不是一堆通用模板。

---

阶段 1 — 自动发现

先探索，再编写任何内容。并行启动三个子 Agent以提高效率——每个子 Agent 负责一项独立的调研任务。收集完它们的结果后再继续。

子 Agent 调度

同时启动以下三个子 Agent（一次工具调用，包含多个 Agent 调用）：

子 Agent A — 技术栈与命令。 阅读配置文件（package.json、pyproject.toml、go.mod、Cargo.toml、tsconfig.json、Dockerfile、Makefile、.prettierrc*、.eslintrc*、ruff.toml、.golangci.yml 等），并报告：

• 语言及版本
• 运行时和框架（Fastify、Express、Next.js、Django、FastAPI、chi 等）
• 测试框架及测试组织方式
• 数据库和查询层（如有）
• 身份验证机制（如有）
• AI/LLM 库（如有）
• 包管理器
• 类型检查工具（例如 tsc、mypy、pyright）
• 格式化工具（例如 Prettier、Black、Ruff format、gofmt、rustfmt）——请与 Linter 分开说明，因为许多技术栈会将它们作为不同命令运行
• Linter（例如 ESLint、Ruff、golangci-lint、Clippy）
• 以下操作的精确、可直接复制粘贴的命令：设置/安装、运行测试、类型检查、开发服务器、构建、格式化、Lint（检查 package.json 脚本、Makefile 目标、pyproject.toml 脚本、Dockerfile 入口点）。如果格式化和 Lint 共用一个脚本，请说明；如果两者分开，请分别列出。

子 Agent B — 项目结构与约定。 列出顶层目录并报告：

• 识别出的子域（代表应用不同部分的顶层目录）：
  • 单包仓库：通常为 src/、app/、internal/、cmd/
  • 单体仓库：每个 packages/<name>/ 或 apps/<name>/
  • 多部分仓库：backend/、frontend/、server/、client/、api/、web/
  • 忽略：node_modules/、dist/、build/、.git/、测试夹具、配置目录
• 各子域的作用（后端 API、前端应用、共享库、CLI 工具等）
• 文件命名模式（kebab-case、camelCase、snake_case）
• 测试文件的位置（与源文件并置？单独放在 __tests__/ 或 tests/ 目录中？）
• 模块组织风格（按功能？按层？按领域？）
• 现有文档（README.md 内容、任何 docs/ 文件夹）

子 Agent C — Git 平台、CI/CD、钩子与现有文件。 阅读 .git/config，检查 CI 和钩子配置文件，抽查近期提交，并扫描现有文档：

• 根据远程 URL 判断 Git 平台：github.com → GitHub，dev.azure.com / visualstudio.com → Azure DevOps，gitlab.com → GitLab，bitbucket.org → Bitbucket
• CI/CD：.github/workflows/ → GitHub Actions，azure-pipelines.yml → Azure Pipelines，.gitlab-ci.yml → GitLab CI
• Pre-commit 钩子：检查 .husky/、.pre-commit-config.yaml、lefthook.yml/lefthook.yaml、包含非示例文件的 .git/hooks/。如果发现钩子，请报告使用的框架，以及每个钩子运行的内容（打开配置并总结）——Agent 需要知道这些钩子会阻止其提交，而设置部分必须包含安装步骤（pnpm install 会运行 Husky 的 prepare 脚本、pre-commit install、lefthook install 等）。
• 提交消息约定：运行 git log -n 100 --pretty=%s 并报告观察到的模式：
  • Conventional Commits 前缀（feat:、fix:、chore:、带作用域的形式，如 feat(api):）
  • 工单键前缀/后缀（AB#123、PROJ-456、#789）——这可以确认或覆盖基于平台推断的追踪系统
  • 祈使语气还是过去时、行长度惯例，以及在 10 条以上提交中一致的其他模式
  • 如果提交不一致，或仓库提交数量少于约 10 条，请如实说明——不要臆造约定
• 根据相同提交消息中的工单追踪线索（#123 → GitHub Issues，AB#456 → Azure DevOps，PROJ-789 → Jira/Linear）
• CLAUDE.md、AGENTS.md 或 README.md 是否存在，以及是否包含实质内容（简要总结其中内容）

子代理返回后

将三份报告合并为统一的概览。如果有子代理无法确定某项信息（例如，未发现数据库或 CI），没关系，注明“未检测到”并继续。

对于现有文件：

• 从 README 中提取项目描述，写入根目录的 AGENTS.md 简介
• 将文档中记录的约定纳入 ENGINEERING.md
• 如果现有的 AGENTS.md 或 CLAUDE.md 为空或只是占位内容，请替换它
• 如果 CLAUDE.md 已有实质内容，请保留——它有不同用途

---

阶段 2 — 确认发现并收集指南

展示你的发现，并逐项说明每个决定。

2a. 展示发现

以格式化摘要向用户展示你发现的内容：

Here's what I found:

  Stack:        [language] / [framework] / [db] / [test framework]
  Format/Lint:  [formatter] / [linter]  (or "shared: <tool>" if same)
  Platform:     [GitHub | Azure DevOps | GitLab | Bitbucket | unknown]
  CI:           [GitHub Actions | Azure Pipelines | GitLab CI | none detected]
  Tracker:      [GitHub Issues | Azure DevOps | Jira | Linear | none detected]
  Commits:      [Conventional Commits | ticket-prefixed | freeform | none detected]
  Hooks:        [Husky | pre-commit | lefthook | none detected]
  Subdomains:   [list of discovered subdomains]

然后使用 AskUserQuestion 在一次调用中确认发现并询问工作跟踪方式。如果已明确检测到跟踪工具，则跳过跟踪工具相关问题。每次调用最多可询问 4 个问题——根据情况合并提问。

questions:
  - question: "Does this look right, or should I correct anything?"
    header: "Findings"
    multiSelect: false
    options:
      - label: "Looks good (Recommended)"
        description: "Proceed with the detected stack, platform, and subdomains as shown above."
      - label: "Needs corrections"
        description: "I'll tell you what to fix before we continue."
  - question: "Where do you track issues / work items?"
    header: "Tracker"
    multiSelect: false
    options:
      - label: "GitHub Issues"
        description: "Issues tracked in GitHub, linked with #123 in commits and PRs."
      - label: "Azure DevOps"
        description: "Work items tracked in Azure DevOps, linked with AB#123."
      - label: "Jira"
        description: "Issues tracked in Jira, linked with PROJECT-123."
      - label: "Linear"
        description: "Issues tracked in Linear, linked with TEAM-123."

如果用户选择“需要更正”，请等待用户提供更正后再继续。

2b. 组织指南（可选）

使用 AskUserQuestion 询问组织指南：

questions:
  - question: "Do you have coding guidelines or standards to include?"
    header: "Guidelines"
    multiSelect: false
    options:
      - label: "Skip"
        description: "No org-specific guidelines — use only the auto-detected conventions."
      - label: "Yes, I'll provide them"
        description: "I'll paste a file path, URL, or content to weave into ENGINEERING.md."

如果用户选择提供指南，请等待用户输入。将其纳入 ENGINEERING.md 的相关章节（编码标准、命名约定、审查实践等）。不要逐字照搬——应将其与针对技术栈的标准自然融合。

---

阶段 3 — 脚手架生成原样文件（脚本）

运行脚手架脚本，创建所有确定性文件——目录、通用模板、组合后的 AGENT_WORKFLOW.md，以及 CLAUDE.md 桥接文件。这样可以避免使用 LLM 生成原样内容，从而节省 token。

bash scripts/scaffold.sh --target <repo-root> --platform <platform>

--platform 标志决定注入 agents-docs/AGENT_WORKFLOW.md 的 PR/MR 工作流章节。脚手架默认生成到 agents-docs/，它与任何现有的 docs/ 并列，因此不会影响由人工维护的项目文档。如果有充分理由将 Agent 文件树放到其他位置（例如 docs/agents），可以使用可选的 --docs-dir <dir> 标志，但几乎总是应使用默认值。

脚本会创建以下文件：

文件	方式
CLAUDE.md	创建（如果已存在则追加）——引导 Claude 查看 AGENTS.md
agents-docs/AGENT_WORKFLOW.md	由基础模板和平台 PR/MR 章节组合而成
agents-docs/AGENTS_FEATURES.md	原样复制——通用功能文档约定
agents-docs/AGENTS_CONTEXT.md	原样复制——CONTEXT.md 的使用者/提供者约定
agents-docs/AGENTS_ADRS.md	原样复制——ADR 的使用者/提供者约定
agents-docs/features/feature-template.md	原样复制——未来功能文档的模板
agents-docs/LESSONS.md	原样复制——经验文件格式及一个预置示例
agents-docs/adr/0001-record-architectural-decisions.md	原样复制——预置的元 ADR，用于演示 Nygard 简版格式

脚本具有幂等性——重新运行时会跳过现有文件。

可用脚本

• scripts/scaffold.sh — 生成原样文件并组合 AGENT_WORKFLOW.md

---

阶段 4 — 生成项目专属文件（LLM）

这些文件需要 LLM 推理，无法通过脚本生成。编写前请阅读参考文件：

• references/file-templates.md — 各文件的基础模板
• references/tech-adapters.md — 技术栈专属章节
• references/platform-adapters.md — ENGINEERING.md 中的 CI/CD 和问题关联章节

将每个 {{placeholder}} 替换为你实际发现的内容。参考文件中凡是涉及 Agent 文档根目录路径的地方，均使用 {{DOCS_DIR}}——编写每个文件时，请将其替换为 agents-docs（如果通过 --docs-dir 覆盖了默认值，则替换为相应值）。最终输出中不得保留占位符。每个生成的文件都应读起来像是由本项目的资深工程师撰写的。

要生成的文件

文件	用途
/AGENTS.md	入口点——链接到文档、关键规则、完成检查清单
agents-docs/ENGINEERING.md	工程标准——测试、语言、命名、数据库、身份验证、CI/CD、命令
agents-docs/FEATURES.md	功能领域索引（从精简或空白开始）
<subdomain>/CONTEXT.md	每个已发现子域各一份——承载领域信息：词汇、关系、输入输出、不变量
agents-docs/CONTEXT-MAP.md	仅当子域数量 ≥2 时生成——有界上下文及跨上下文关系的索引

子域 CONTEXT.md 规则

在每个子域的顶层创建一份 CONTEXT.md，不要放得更深：

• src/ → src/CONTEXT.md（不要放在 src/routes/CONTEXT.md）
• internal/ → internal/CONTEXT.md（不要放在 internal/handlers/CONTEXT.md）
• packages/auth/ → packages/auth/CONTEXT.md
• frontend/ → frontend/CONTEXT.md

每份子域 CONTEXT.md 都涵盖其子树中的所有内容。不要为工具文件夹、配置目录或生成的输出创建此文件。

内容应承载领域信息，而非流程步骤。 文件模板（位于 references/file-templates.md）包含以下部分：词汇、关系、边界 / 输入输出、不变量、待确认的歧义。应尽早搭建骨架，让 Agent 知道该写什么；但只有在第一阶段实际发现的内容，才填入相应部分：

• 词汇：除非第一阶段发现了明确的领域术语（路由名称、表名、独特的类型名称），否则保留带占位行的表格。不要编造条目——agents-docs/AGENT_WORKFLOW.md 中的生产者触发器会在后续逐步填入。
• 边界 / 输入输出：根据观察到的入口点（HTTP 路由、事件处理器、导出的模块）填写。如不明确，保留占位内容。
• 不变量：搭建骨架时通常留空——这些内容会在使用过程中逐步显现。

Agent 流程规则（TDD、类型检查、关注领域）不应放入 CONTEXT.md。这些内容应放在 /AGENTS.md 和 agents-docs/ENGINEERING.md 中。

CONTEXT-MAP.md 规则

仅当至少有 2 个子域各自拥有 CONTEXT.md 时，才生成 agents-docs/CONTEXT-MAP.md。 只有单一上下文的代码仓库应完全跳过此文件。

根据第一阶段的发现填写——每个子域一行，包含名称、简要用途、观察到的公开接口（HTTP 路由 / 发出的事件 / 导出的类型），以及其 CONTEXT.md 的路径。关系部分记录探索过程中观察到的跨上下文耦合（共享类型、事件流、依赖方向）。如果从代码中无法明确关系，则在该部分保留一个占位项目符号；后续会逐步填入。

功能索引

agents-docs/FEATURES.md 应从精简内容开始。只有发现有实质性实现的功能领域时，才添加条目——仅有路由存根或空处理器不算。即使添加条目，也只添加索引条目；不要创建 agents-docs/features/<area>.md 文件本身。

AGENTS.md 和 ENGINEERING.md 中的平台专属内容

将 references/platform-adapters.md 中的平台内容融入生成的文件：

• AGENTS.md 完成检查清单：添加平台专属事项（已创建 PR、CI 通过、已关联问题）
• agents-docs/ENGINEERING.md：添加 CI/CD 部分和问题关联约定

如果未检测到平台，且用户也未指定平台，则完全省略平台专属部分——不要猜测。

注意：agents-docs/AGENT_WORKFLOW.md 已由脚本处理，并包含正确的平台部分。

Phase-1 信号应写入的位置

发现阶段会收集一些超出技术栈和平台范围的信号——确保每一项都写入正确的文件：

• 格式化工具和代码检查工具（Subagent A）：在 agents-docs/ENGINEERING.md 的命令部分将两者列为不同的命令。如果项目用一个脚本运行两者，请说明；否则分别记录。将格式化工具也列入完成检查清单，与类型检查和测试并列。
• 提交前钩子（Subagent C）：如果发现了钩子，请在 agents-docs/ENGINEERING.md 的设置部分记录所用框架和安装步骤（pre-commit install、lefthook install 或“Husky 会在 pnpm install 时自动安装”），并在 AGENTS.md 中添加简短说明，让 Agent 知道提交会受到检查。注明每个钩子会运行什么，让 Agent 了解提交被拒绝的原因。
• 提交规范（Subagent C）：如果发现了明确的模式，请在 agents-docs/ENGINEERING.md 的提交消息部分记录，并提供一个符合仓库实际风格的示例。如果提交风格不一致或数量太少，无法判断模式，请省略此部分，不要默认强加 Conventional Commits。
• 子域（Subagent B）：为每个检测到的子域创建一个体现领域名称的 <subdomain>/CONTEXT.md（先搭建骨架，再根据观察到的入口点和命名填充内容）。如果存在 ≥2 个子域，还要生成 agents-docs/CONTEXT-MAP.md，每个子域占一行。单一子域的仓库无需创建映射文件。

调整预置的 agents-docs/LESSONS.md 示例

脚手架脚本会原样复制 agents-docs/LESSONS.md，而预置示例使用 npx tsc --noEmit 作为占位类型检查命令。脚本运行后，请编辑示例，使其符合本项目实际使用的类型检查命令：

• TypeScript → 保留 npx tsc --noEmit（或替换为 package.json 中的准确脚本，例如 pnpm typecheck）
• Python（mypy） → 替换为 mypy .（或项目使用的准确命令）
• Python（pyright） → 替换为 pyright
• Go → 替换为 go vet ./...
• Rust → 替换为 cargo check 或 cargo clippy
• 无静态类型检查 → 将整个示例替换为适合该技术栈的验证步骤（例如，对于 JS 项目：“运行项目的代码检查命令，并在声称‘已完成’前确认退出码为 0。”）

更新示例的标题、触发条件、规则和示例代码块，使其与项目匹配——这样，Agent 读到预置示例时，看到的才是本仓库中真实可运行的命令。技术栈不匹配的示例还不如没有示例。

---

什么样的输出才算好

具体，而非泛泛而谈。 如果仓库使用 Vitest，就写“Vitest”，而不是“你的测试框架”。如果类型检查命令是 npx tsc --noEmit，就原样写出。

使用项目的实际名称。 使用在 README、package.json 或 go.mod 中找到的项目名称，而不是推断或杜撰名称。

命令准确。 测试、类型检查、开发服务器、构建和设置命令都必须正确，并且可直接复制粘贴运行。

适度。 纯前端仓库不要添加“数据库指南”部分。Python 项目不要添加“TypeScript 标准”。只包含适用的内容。

关键之处要有明确立场。 无论技术栈如何，这些规则都必须包含：

• TDD（red-green-refactor）是强制要求
• 非简单任务必须使用计划模式
• 标记工作完成前必须进行验证
• 自我改进循环（吸取经验教训）
• 功能文档要求

保持根目录中的 AGENTS.md 精简。 它是索引，并包含最关键的不可妥协规则。详细内容放在它指向的文档中。

生成后

告诉用户：

1. 创建了哪些文件（包含完整路径的清单）
2. 检测到了哪些子域，并为其分别创建了 CONTEXT.md
3. 平台专属内容使用了哪个平台／跟踪系统
4. 对哪些技术栈细节不确定——如实说明尚不清楚的部分
5. 提交前需要检查和自定义哪些内容

然后推荐后续工作流，用于填充此脚手架创建的空 agents-docs/features/ 目录：

建议的下一步：完善功能文档。

脚手架有意将 agents-docs/features/ 留空。最快的填充方式是使用 Mimas 仓库中的两个技能，并在全新的会话中依次运行：

1. find-features — 扫描代码库，识别有意义的功能区域，并将其添加到 agents-docs/FEATURES.md。
2. document-feature — 通过引导式演练，根据模板将每个已识别的区域整理成完整的 agents-docs/features/<area>.md。

这两个技能（以及其他值得了解的技能）都位于 https://github.com/Grade-AI-Labs/Mimas。安装后，先运行 find-features，再针对它找到的内容循环运行 document-feature。

完成后，检查生成的文件并提交。