setup-agentic-repository

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

setup-agentic-repository

配置Agent化仓库

You are scaffolding a set of instruction files that AI agents read at the start of every session to understand how to work on a project. The output is a complete, project-specific instruction tree — not a generic template dump.

你正在搭建一套AI代理在每次会话开始时读取的指令文件，以便其理解如何处理项目。输出内容是一套完整的、针对特定项目的指令树——而非通用模板的堆砌。

Phase 1 — Automated Discovery

第一阶段：自动发现

Explore before writing anything. Launch three subagents in parallel to maximize speed — each handles an independent research task. Collect their results before proceeding.

在编写任何内容前先进行探索。并行启动三个子代理以最大化效率——每个子代理负责一项独立的调研任务。在继续下一步前收集它们的结果。

Subagent dispatch

子代理调度

Launch these three subagents simultaneously (one tool call with multiple Agent invocations):

Subagent A — Tech stack & commands. Read config files (

package.json

pyproject.toml

go.mod

Cargo.toml

tsconfig.json

Dockerfile

Makefile

.prettierrc*

.eslintrc*

ruff.toml

.golangci.yml

, etc.) and report:

Language(s) and version(s)
Runtime and framework (Fastify, Express, Next.js, Django, FastAPI, chi, etc.)
Test framework and how tests are organized
Database and query layer (if any)
Authentication mechanism (if any)
AI/LLM libraries (if any)
Package manager
Type checking tool (e.g., tsc, mypy, pyright)
Formatter (e.g., Prettier, Black, Ruff format, gofmt, rustfmt) — note this separately from the linter, since many stacks run them as distinct commands
Linter (e.g., ESLint, Ruff, golangci-lint, Clippy)
Exact, copy-pasteable commands for: setup/install, running tests, type checking, dev server, build, format, lint (check
```
package.json
```
scripts,
```
Makefile
```
targets,
```
pyproject.toml
```
scripts,
```
Dockerfile
```
entrypoints). If format and lint share a script, say so; if they're distinct, capture both.

Subagent B — Project structure & conventions. List top-level directories and report:

Subdomains identified (top-level dirs that represent distinct parts of the app):
- Single-package repos: typically
```
src/
```
  ,
```
app/
```
  ,
```
internal/
```
  ,
```
cmd/
```
- Monorepos: each
```
packages/<name>/
```
  or
```
apps/<name>/
```
- Multi-part repos:
```
backend/
```
  ,
```
frontend/
```
  ,
```
server/
```
  ,
```
client/
```
  ,
```
api/
```
  ,
```
web/
```
- Ignore:
```
node_modules/
```
  ,
```
dist/
```
  ,
```
build/
```
  ,
```
.git/
```
  , test fixtures, config dirs
Role of each subdomain (backend API, frontend app, shared library, CLI tool, etc.)
File naming pattern (kebab-case, camelCase, snake_case)
Test file placement (colocated? separate
```
__tests__/
```
or
```
tests/
```
dir?)
Module organization style (by feature? by layer? by domain?)
Existing documentation (README.md content, any docs/ folder)

Subagent C — Git platform, CI/CD, hooks & existing files. Read

.git/config

, check for CI and hook config files, sample recent commits, and scan existing docs:

Git platform from remote URL:
```
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 hooks: check for
```
.husky/
```
,
```
.pre-commit-config.yaml
```
,
```
lefthook.yml
```
/
```
lefthook.yaml
```
,
```
.git/hooks/
```
with non-sample files. If found, report which framework is in use and what each hook runs (open the config and summarize) — agents need to know these will block their commits, and the setup section must include the install step (
```
pnpm install
```
runs Husky's prepare script,
```
pre-commit install
```
,
```
lefthook install
```
, etc.).
Commit message conventions: run
```
git log -n 100 --pretty=%s
```
and report patterns you observe:
- Conventional Commits prefixes (
```
feat:
```
  ,
```
fix:
```
  ,
```
chore:
```
  , scopes like
```
feat(api):
```
  )
- Ticket-key prefixes/suffixes (
```
AB#123
```
  ,
```
PROJ-456
```
  ,
```
#789
```
  ) — this confirms or overrides the platform-based tracker guess
- Imperative vs. past tense, line-length norms, anything else consistent across 10+ commits
- If commits are inconsistent or the repo has fewer than ~10 commits, say so — don't invent a convention
Issue tracker hints from those same commit messages (
```
#123
```
→ GitHub Issues,
```
AB#456
```
→ Azure DevOps,
```
PROJ-789
```
→ Jira/Linear)
Whether
```
CLAUDE.md
```
,
```
AGENTS.md
```
, or
```
README.md
```
exist and have meaningful content (report a brief summary of what they contain)

同时启动这三个子代理（一次工具调用中包含多个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）——与代码检查工具分开记录，因为许多技术栈会将它们作为独立命令运行
代码检查工具（如ESLint、Ruff、golangci-lint、Clippy）
可直接复制粘贴的精确命令：安装配置、运行测试、类型检查、开发服务器、构建、格式化、代码检查（查看
```
package.json
```
脚本、
```
Makefile
```
目标、
```
pyproject.toml
```
脚本、
```
Dockerfile
```
入口点）。如果格式化和代码检查共用一个脚本，请注明；如果是独立命令，请分别记录。

子代理B：项目结构与约定。列出顶级目录并报告：

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

子代理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
预提交钩子：检查是否存在
```
.husky/
```
、
```
.pre-commit-config.yaml
```
、
```
lefthook.yml
```
/
```
lefthook.yaml
```
、
```
.git/hooks/
```
中的非示例文件。如果找到，报告使用的框架以及每个钩子运行的内容（打开配置文件并总结）——代理需要知道这些钩子会阻止提交，且配置部分必须包含安装步骤（
```
pnpm install
```
会运行Husky的prepare脚本、
```
pre-commit install
```
、
```
lefthook install
```
等）。
提交消息约定：运行
```
git log -n 100 --pretty=%s
```
并报告观察到的模式：
- 约定式提交前缀（
```
feat:
```
  、
```
fix:
```
  、
```
chore:
```
  ，如
```
feat(api):
```
  这样的作用域）
- 工单密钥前缀/后缀（
```
AB#123
```
  、
```
PROJ-456
```
  、
```
#789
```
  ）——这会确认或覆盖基于平台的追踪工具猜测
- 祈使语气 vs 过去式、行长度规范、其他跨10+提交的一致模式
- 如果提交不一致或仓库提交数少于约10次，请注明——不要凭空创造约定
从相同提交消息中获取问题追踪工具提示（
```
#123
```
→ GitHub Issues，
```
AB#456
```
→ Azure DevOps，
```
PROJ-789
```
→ Jira/Linear）
是否存在
```
CLAUDE.md
```
、
```
AGENTS.md
```
或
```
README.md
```
且包含有意义的内容（简要报告它们的内容）

After subagents return

子代理返回结果后

Combine the three reports into a unified picture. If any subagent couldn't determine something (e.g., no database found, no CI detected), that's fine — note it as "not detected" and move on.

For existing files:

Pull project description from README into root
```
AGENTS.md
```
intro
Incorporate documented conventions into
```
ENGINEERING.md
```
If an existing
```
AGENTS.md
```
or
```
CLAUDE.md
```
is empty or placeholder, replace it
If there is a populated
```
CLAUDE.md
```
, keep it — it serves a different purpose

将三份报告整合成统一的信息。如果任何子代理无法确定某些内容（如未找到数据库、未检测到CI），无需担心——标注为“未检测到”并继续。

对于现有文件：

将README中的项目描述提取到根目录
```
AGENTS.md
```
的引言部分
将已记录的约定整合到
```
ENGINEERING.md
```
中
如果现有
```
AGENTS.md
```
或
```
CLAUDE.md
```
为空或占位符，则替换它们
如果存在内容充实的
```
CLAUDE.md
```
，则保留它——它有不同的用途

Phase 2 — Confirm findings and gather guidelines

第二阶段：确认发现并收集指南

Present your findings and walk through each decision.

展示你的发现并逐一说明每个决策。

2a. Present findings

2a. 展示发现

Show the user what you discovered as a formatted summary:

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]

Then use

AskUserQuestion

to confirm findings and ask about work tracking in a single call. If the tracker was confidently detected, skip the tracker question. You can ask up to 4 questions per call — batch what makes sense.

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."

If the user picks "Needs corrections", wait for their corrections before continuing.

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

以下是我的发现：

  技术栈：        [语言] / [框架] / [数据库] / [测试框架]
  格式化/检查：  [格式化工具] / [代码检查工具] （如果是同一工具则标注“共用：<工具>”）
  平台：     [GitHub | Azure DevOps | GitLab | Bitbucket | 未知]
  CI：           [GitHub Actions | Azure Pipelines | GitLab CI | 未检测到]
  追踪工具：      [GitHub Issues | Azure DevOps | Jira | Linear | 未检测到]
  提交约定：      [约定式提交 | 工单前缀 | 自由格式 | 未检测到]
  钩子：        [Husky | pre-commit | lefthook | 未检测到]
  子域：   [已发现的子域列表]

然后使用

AskUserQuestion

在一次调用中确认发现并询问工作追踪相关问题。如果已确定追踪工具，则跳过追踪工具问题。每次调用最多可问4个问题——合理批量提问。

questions:
  - question: "这些内容是否正确，是否需要我修改？"
    header: "发现结果"
    multiSelect: false
    options:
      - label: "看起来没问题（推荐）"
        description: "按照上述检测到的技术栈、平台和子域继续进行。"
      - label: "需要修改"
        description: "我会告诉你需要修正的内容，然后再继续。"
  - question: "你们在哪里追踪问题/工作项？"
    header: "追踪工具"
    multiSelect: false
    options:
      - label: "GitHub Issues"
        description: "问题在GitHub中追踪，提交和PR中使用#123链接。"
      - label: "Azure DevOps"
        description: "工作项在Azure DevOps中追踪，使用AB#123链接。"
      - label: "Jira"
        description: "问题在Jira中追踪，使用PROJECT-123链接。"
      - label: "Linear"
        description: "问题在Linear中追踪，使用TEAM-123链接。"

如果用户选择“需要修改”，等待用户提供修改内容后再继续。

2b. Org guidelines (optional)

2b. 组织指南（可选）

Use

AskUserQuestion

to ask about org guidelines:

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."

If the user chooses to provide guidelines, wait for their input. Incorporate it into the relevant sections of

ENGINEERING.md

(coding standards, naming conventions, review practices, etc.). Don't dump it verbatim — integrate it naturally alongside the tech-stack-specific standards.

使用

AskUserQuestion

询问组织相关指南：

questions:
  - question: "你们是否有需要纳入的编码指南或标准？"
    header: "指南"
    multiSelect: false
    options:
      - label: "跳过"
        description: "无组织特定指南——仅使用自动检测到的约定。"
      - label: "有，我会提供"
        description: "我会粘贴文件路径、URL或内容，将其整合到ENGINEERING.md中。"

如果用户选择提供指南，等待用户输入。将其整合到

ENGINEERING.md

的相关章节（编码标准、命名约定、评审流程等）中。不要直接粘贴原文——要与技术栈特定标准自然融合。

Phase 3 — Scaffold verbatim files (script)

第三阶段：搭建逐字文件（脚本）

Run the scaffolding script to create all deterministic files — directories, universal templates, composed AGENT_WORKFLOW.md, and the CLAUDE.md bridge file. This saves tokens by avoiding LLM generation of verbatim content.

bash

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

The

--platform

flag determines which PR/MR workflow section is injected into

agents-docs/AGENT_WORKFLOW.md

. The scaffold lands in

agents-docs/

by default — a sibling of any existing

docs/

, so human-maintained project docs stay untouched. An optional

--docs-dir <dir>

flag is available if you have a strong reason to put the agent tree elsewhere (e.g.

docs/agents

), but the default is the right answer almost always.

The script creates:

File	How
`CLAUDE.md`	Created (or appended if exists) — points Claude to AGENTS.md
`agents-docs/AGENT_WORKFLOW.md`	Composed from base template + platform PR/MR section
`agents-docs/AGENTS_FEATURES.md`	Copied verbatim — universal feature doc contract
`agents-docs/AGENTS_CONTEXT.md`	Copied verbatim — CONTEXT.md consumer/producer contract
`agents-docs/AGENTS_ADRS.md`	Copied verbatim — ADR consumer/producer contract
`agents-docs/features/feature-template.md`	Copied verbatim — template for future feature docs
`agents-docs/LESSONS.md`	Copied verbatim — lessons-file format and one seeded example
`agents-docs/adr/0001-record-architectural-decisions.md`	Copied verbatim — seeded meta-ADR demonstrating the Nygard short form

The script is idempotent — re-running skips existing files.

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

bash

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

--platform

标志决定了哪个PR/MR工作流章节会被注入到

agents-docs/AGENT_WORKFLOW.md

中。默认情况下，搭建内容会放在

agents-docs/

目录下——与现有

docs/

目录同级，因此人工维护的项目文档不会被改动。如果你有充分理由将代理树放在其他位置（如

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短格式

脚本具有幂等性——重新运行会跳过已存在的文件。

Available scripts

可用脚本

scripts/scaffold.sh
— Scaffolds verbatim files and composes AGENT_WORKFLOW.md

scripts/scaffold.sh
—— 搭建逐字文件并组合AGENT_WORKFLOW.md

Phase 4 — Generate project-specific files (LLM)

第四阶段：生成项目特定文件（LLM）

These files require LLM reasoning and cannot be scripted. Read the reference files before writing:

```
references/file-templates.md
```
— base template for each file
```
references/tech-adapters.md
```
— tech-stack-specific sections
```
references/platform-adapters.md
```
— CI/CD and issue linking sections for ENGINEERING.md

Replace every

{{placeholder}}

with what you actually discovered. The references use

{{DOCS_DIR}}

wherever the agent docs root path appears — substitute

agents-docs

for every occurrence as you write each file (or whatever value was passed to

--docs-dir

if it was overridden). Don't leave the placeholder in final output. Every generated file should read as if a senior engineer on this project wrote it.

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

```
references/file-templates.md
```
—— 每个文件的基础模板
```
references/tech-adapters.md
```
—— 技术栈特定章节
```
references/platform-adapters.md
```
—— ENGINEERING.md中的CI/CD和问题链接章节

将所有

{{placeholder}}

替换为你实际发现的内容。参考文件中凡是出现代理文档根路径的地方都使用

{{DOCS_DIR}}

——在编写每个文件时将其替换为

agents-docs

（如果使用

--docs-dir

覆盖了默认值，则替换为对应的值）。最终输出中不要保留占位符。每个生成的文件都应看起来像是该项目的资深工程师编写的。

Files to generate

要生成的文件

File	Purpose
`/AGENTS.md`	Entry point — links to docs, critical rules, completion checklist
`agents-docs/ENGINEERING.md`	Engineering standards — testing, language, naming, DB, auth, CI/CD, commands
`agents-docs/FEATURES.md`	Feature area index (start minimal or empty)
`<subdomain>/CONTEXT.md`	One per discovered subdomain — domain-bearing: vocabulary, relationships, IO, invariants
`agents-docs/CONTEXT-MAP.md`	Only when ≥2 subdomains — index of bounded contexts and cross-context relationships

文件	用途
`/AGENTS.md`	入口点——链接到文档、关键规则、完成检查清单
`agents-docs/ENGINEERING.md`	工程标准——测试、语言、命名、数据库、认证、CI/CD、命令
`agents-docs/FEATURES.md`	功能区域索引（初始时保持极简或为空）
`<subdomain>/CONTEXT.md`	每个已发现的子域对应一个——包含领域相关内容：词汇、关系、输入输出、不变量
`agents-docs/CONTEXT-MAP.md`	仅当子域数量≥2时生成——有界上下文索引及跨上下文关系

Subdomain CONTEXT.md rules

子域CONTEXT.md规则

Create one

CONTEXT.md

at the top level of each subdomain — not deeper:

```
src/
```
→
```
src/CONTEXT.md
```
(not
```
src/routes/CONTEXT.md
```
)

internal/

→

internal/CONTEXT.md

(not

internal/handlers/CONTEXT.md

)

```
packages/auth/
```
→
```
packages/auth/CONTEXT.md
```
```
frontend/
```
→
```
frontend/CONTEXT.md
```

Each subdomain CONTEXT.md covers everything within its subtree. Don't create them for utility folders, config dirs, or generated output.

Content is domain-bearing, not procedural. The file template (in

references/file-templates.md

) has these sections: Vocabulary, Relationships, Boundaries / IO, Invariants, Flagged ambiguities. Scaffold the skeleton eagerly so agents know where to write, but only populate sections from what you actually discovered in Phase 1:

Vocabulary: leave the table with a placeholder row unless Phase 1 surfaced clear domain terms (route names, table names, distinctive type names). Don't invent entries — the producer triggers in
```
agents-docs/AGENT_WORKFLOW.md
```
fill it in lazily.
Boundaries / IO: populate from observed entry points (HTTP routes, event handlers, exported modules). If unclear, leave a placeholder.
Invariants: usually empty at scaffold time — these emerge during use.

Agent-procedural rules (TDD, typecheck, focus areas) do NOT belong in

CONTEXT.md

. Those live in

/AGENTS.md

and

agents-docs/ENGINEERING.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

）包含以下章节：词汇、关系、边界/输入输出、不变量、标记的歧义点。提前搭建框架以便代理知道在哪里编写内容，但仅填充第一阶段实际发现的内容：

词汇：除非第一阶段发现明确的领域术语（路由名称、表名、独特类型名称），否则保留带有占位符行的表格。不要凭空创建条目——
```
agents-docs/AGENT_WORKFLOW.md
```
中的生成触发器会逐步填充内容。
边界/输入输出：从观察到的入口点（HTTP路由、事件处理器、导出模块）填充内容。如果不明确，保留占位符。
不变量：通常在搭建时为空——这些内容会在使用过程中逐渐出现。

代理流程规则（TDD、类型检查、重点领域）不属于

CONTEXT.md

的内容。这些内容应放在

/AGENTS.md

和

agents-docs/ENGINEERING.md

中。

CONTEXT-MAP.md rules

CONTEXT-MAP.md规则

Generate

agents-docs/CONTEXT-MAP.md

only when ≥2 subdomains have their own

CONTEXT.md

. Single-context repos skip this file entirely.

Populate from Phase 1 discoveries — one row per subdomain with name, one-line purpose, observed public surface (HTTP routes / events emitted / exported types), and the path to its

CONTEXT.md

. The Relationships section captures cross-context coupling observed during exploration (shared types, event flows, dependency direction). If relationships aren't obvious from the code, leave the section with a placeholder bullet — they get filled in lazily.

仅当≥2个子域拥有自己的
CONTEXT.md
时，才生成

agents-docs/CONTEXT-MAP.md

。单上下文仓库跳过此文件。

根据第一阶段的发现填充内容——每个子域对应一行，包含名称、一行描述、观察到的公共接口（HTTP路由/发出的事件/导出的类型），以及其

CONTEXT.md

的路径。关系章节记录探索过程中观察到的跨上下文耦合（共享类型、事件流、依赖方向）。如果从代码中无法明确关系，保留带有占位符项目符号的章节——这些内容会逐步填充。

Feature index

功能索引

agents-docs/FEATURES.md

should start minimal. Only add entries if you found feature domains with meaningful implementation — not just a route stub or empty handler. Even when you add entries, only add index entries — do not create the

agents-docs/features/<area>.md

files themselves.

agents-docs/FEATURES.md

初始时应保持极简。仅当发现具有有意义实现的功能领域时才添加条目——不要仅因为存在路由 stub 或空处理器就添加条目。即使添加条目，也仅添加索引条目——不要创建

agents-docs/features/<area>.md

文件本身。

Platform-specific content in AGENTS.md and ENGINEERING.md

AGENTS.md和ENGINEERING.md中的平台特定内容

Weave platform content from

references/platform-adapters.md

into the files you generate:

AGENTS.md
completion checklist: add platform-specific items (PR opened, CI passing, issues linked)
agents-docs/ENGINEERING.md
: add CI/CD section and issue linking conventions

If no platform was detected and the user didn't specify one, omit platform-specific sections entirely — don't guess.

Note:

agents-docs/AGENT_WORKFLOW.md

is already handled by the script with the correct platform section.

将

references/platform-adapters.md

中的平台内容整合到你生成的文件中：

AGENTS.md
完成检查清单：添加平台特定项（已打开PR、CI通过、已链接问题）
agents-docs/ENGINEERING.md
：添加CI/CD章节和问题链接约定

如果未检测到平台且用户未指定，则完全省略平台特定章节——不要猜测。

注意：

agents-docs/AGENT_WORKFLOW.md

已由脚本处理，包含正确的平台章节。

Where Phase-1 signals land

第一阶段信号的存放位置

The discovery phase captures a few signals beyond stack and platform — make sure each one shows up in the right file:

Formatter and linter (Subagent A): list both as distinct commands in the
```
agents-docs/ENGINEERING.md
```
commands section. If the project runs them as one script, say so; otherwise document each. Mention the formatter in the completion checklist alongside typecheck/tests.
Pre-commit hooks (Subagent C): if hooks were found, document the framework and install step (
```
pre-commit install
```
,
```
lefthook install
```
, or "Husky installs automatically on
```
pnpm install
```
") in
```
agents-docs/ENGINEERING.md
```
under setup, and add a short note in
```
AGENTS.md
```
so agents know commits will be gated. Name what each hook runs so agents understand why a commit was rejected.
Commit conventions (Subagent C): if a clear pattern was detected, document it in
```
agents-docs/ENGINEERING.md
```
(commit-message section) with one example matching the repo's actual style. If commits are inconsistent or too few to draw a pattern from, omit this section rather than imposing Conventional Commits by default.
Subdomains (Subagent B): each detected subdomain gets a domain-bearing
```
<subdomain>/CONTEXT.md
```
(skeleton scaffolded, content populated from observed entry points and naming). If ≥2 subdomains exist, also generate
```
agents-docs/CONTEXT-MAP.md
```
with one row per subdomain. Single-subdomain repos skip the map.

发现阶段捕获了技术栈和平台之外的一些信号——确保每个信号都放在正确的文件中：

格式化工具和代码检查工具（子代理A）：在
```
agents-docs/ENGINEERING.md
```
的命令章节中分别列出两者。如果项目将它们作为一个脚本运行，请注明；否则分别记录。在完成检查清单中与类型检查/测试一起提及格式化工具。
预提交钩子（子代理C）：如果发现钩子，在
```
agents-docs/ENGINEERING.md
```
的配置章节中记录框架和安装步骤（
```
pre-commit install
```
、
```
lefthook install
```
或“Husky会在
```
pnpm install
```
时自动安装”），并在
```
AGENTS.md
```
中添加简短说明，以便代理知道提交会被拦截。注明每个钩子运行的内容，以便代理理解提交被拒绝的原因。
提交约定（子代理C）：如果检测到明确的模式，在
```
agents-docs/ENGINEERING.md
```
的提交消息章节中记录，并提供一个符合仓库实际风格的示例。如果提交不一致或数量太少无法总结模式，则省略此章节，不要默认强加约定式提交。
子域（子代理B）：每个检测到的子域都会获得一个与领域相关的
```
<subdomain>/CONTEXT.md
```
（搭建框架，从观察到的入口点和命名填充内容）。如果子域数量≥2，还需生成
```
agents-docs/CONTEXT-MAP.md
```
，每个子域对应一行。单子域仓库跳过此映射文件。

Tailor the seeded

agents-docs/LESSONS.md

example

定制预置的

agents-docs/LESSONS.md

示例

The scaffold script copies

agents-docs/LESSONS.md

verbatim, and the seeded example uses

npx tsc --noEmit

as a placeholder typecheck command. After the script runs, edit the example so it matches this project's actual typecheck command:

TypeScript → leave
```
npx tsc --noEmit
```
(or substitute the exact script from
```
package.json
```
, e.g.
```
pnpm typecheck
```
)
Python (mypy) → swap to
```
mypy .
```
(or the project's exact invocation)
Python (pyright) → swap to
```
pyright
```
Go → swap to
```
go vet ./...
```
Rust → swap to
```
cargo check
```
or
```
cargo clippy
```
No static typing → replace the example entirely with a stack-appropriate verification step (e.g. for a JS project: "Run the project's lint command and confirm exit 0 before any 'done' claim.")

Update the example's title, trigger, rule, and example block to match — the whole point is that an agent reading the seeded example sees a real, runnable command from this repo. A wrong-stack example is worse than no example.

搭建脚本会直接复制

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。”）

更新示例的标题、触发条件、规则和示例块以匹配——核心目的是让读取预置示例的代理看到该仓库真实可运行的命令。错误技术栈的示例比没有示例更糟糕。

What makes a good output

优质输出的标准

Specific, not generic. If the repo uses Vitest, write "Vitest" — not "your test framework". If type checking is

npx tsc --noEmit

, write exactly that.

Use the actual project name. Refer to the project by the name you found in README, package.json, or go.mod — not a name you inferred or invented.

Accurate commands. Test, typecheck, dev server, build, and setup commands must be correct and copy-pasteable.

Proportionate. Don't add a "Database guidelines" section to a frontend-only repo. Don't add "TypeScript standards" to a Python project. Only include what applies.

Opinionated where it matters. These rules are always included regardless of stack:

TDD (red-green-refactor) is mandatory
Plan mode for non-trivial tasks
Verification before marking work done
Self-improvement loop (lessons learned)
Feature documentation contract

Keep root AGENTS.md lean. It is an index plus the most critical non-negotiable rules. Detail lives in the docs it points to.

具体而非通用。如果仓库使用Vitest，就写“Vitest”——不要写“你的测试框架”。如果类型检查命令是

npx tsc --noEmit

，就精确写出该命令。

使用项目实际名称。使用你在README、package.json或go.mod中找到的项目名称指代项目——不要使用你推断或凭空创造的名称。

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

适度适配。不要为纯前端仓库添加“数据库指南”章节。不要为Python项目添加“TypeScript标准”章节。仅包含适用的内容。

在关键问题上保持主见。无论技术栈如何，以下规则必须包含：

TDD（红-绿-重构）是强制性要求
非琐碎任务需进入规划模式
标记工作完成前需进行验证
自我改进循环（经验总结）
功能文档约定

保持根目录AGENTS.md简洁。它是一个索引加上最关键的不可协商规则。详细内容放在它链接的文档中。

After generating

生成完成后

Tell the user:

Which files were created (full list with paths)
Which subdomains were detected and got their own CONTEXT.md
Which platform/tracker was used for platform-specific content
Any tech stack details you were uncertain about — be honest about gaps
What they should review and customize before committing

Then recommend the follow-up workflow that populates the empty

agents-docs/features/

tree this scaffold creates:

Recommended next step: populate your feature docs.
The scaffold leaves
agents-docs/features/
empty by design. The fastest way to fill it is two skills from the Mimas repo, run back-to-back in fresh sessions:
find-features
— scans the codebase, identifies meaningful feature areas, and adds them to
agents-docs/FEATURES.md
.
document-feature
— guided walkthrough that turns each identified area into a populated
agents-docs/features/<area>.md
from the template.
Both skills (and others worth browsing) live at https://github.com/Grade-AI-Labs/Mimas. Install them, run
find-features
first, then loop
document-feature
over what it found.
Once that's done, review the generated files and commit.

告知用户：

创建了哪些文件（带路径的完整列表）
检测到哪些子域并为其创建了CONTEXT.md
平台特定内容使用了哪个平台/追踪工具
你不确定的任何技术栈细节——如实说明存在的空白
提交前他们应该审查和自定义的内容

然后推荐后续工作流，以填充此搭建过程创建的空

agents-docs/features/

推荐下一步：填充功能文档。
搭建过程特意将
agents-docs/features/
留空。最快的填充方式是使用Mimas仓库中的两个技能，在新会话中连续运行：
find-features
—— 扫描代码库，识别有意义的功能区域，并将其添加到
agents-docs/FEATURES.md
中。
document-feature
—— 引导式流程，将每个识别出的区域从模板转换为内容充实的
agents-docs/features/<area>.md
。
这两个技能（以及其他值得浏览的技能）都位于https://github.com/Grade-AI-Labs/Mimas。安装它们，先运行
find-features
，然后对其识别出的内容循环运行
document-feature
。
完成后，审查生成的文件并提交。

setup-agentic-repository

Original

Translation

setup-agentic-repository

配置Agent化仓库

Phase 1 — Automated Discovery

第一阶段：自动发现

Subagent dispatch

子代理调度

After subagents return

子代理返回结果后

Phase 2 — Confirm findings and gather guidelines

第二阶段：确认发现并收集指南

2a. Present findings

2a. 展示发现

2b. Org guidelines (optional)

2b. 组织指南（可选）

Phase 3 — Scaffold verbatim files (script)

第三阶段：搭建逐字文件（脚本）

Available scripts

可用脚本

Phase 4 — Generate project-specific files (LLM)

第四阶段：生成项目特定文件（LLM）

Files to generate

要生成的文件

Subdomain CONTEXT.md rules

子域CONTEXT.md规则

CONTEXT-MAP.md rules

CONTEXT-MAP.md规则

Feature index

功能索引

Platform-specific content in AGENTS.md and ENGINEERING.md

AGENTS.md和ENGINEERING.md中的平台特定内容

Where Phase-1 signals land

第一阶段信号的存放位置

Tailor the seeded agents-docs/LESSONS.md example

定制预置的agents-docs/LESSONS.md示例

What makes a good output

优质输出的标准

After generating

生成完成后

Tailor the seeded
`agents-docs/LESSONS.md`
example

定制预置的
`agents-docs/LESSONS.md`
示例