ai-repo-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI Repo Setup

AI代码仓库配置

Prepare a repository so AI coding agents can navigate, implement, and verify changes with minimal friction.

Core philosophy: AI agents are new starters with no memory. Every session starts fresh. The codebase itself — not documentation — is the primary context. Only document what is undiscoverable and globally relevant.

为代码仓库做好准备，让AI编码Agent能够以最小的阻力导航、实现和验证变更。

核心理念：AI Agent是没有记忆的新参与者，每次会话都是全新开始。代码库本身——而非文档——是主要上下文。仅记录无法通过代码发现且具有全局相关性的内容。

Inputs to gather (if missing)

需要收集的输入信息（若缺失）

One-sentence project description (what does this project do?)
Functional requirements (what the system should do)
Non-functional requirements (performance, security, scalability constraints)
Business rules (domain logic, validation rules, constraints)
External issue tracker (Linear, Jira, GitHub Issues, ClickUp, etc.) — if used by the team
Behavioral preferences for agents (see step 4 for what to ask)

一句话项目描述（该项目的功能是什么？）
功能需求（系统应该实现什么）
非功能需求（性能、安全、可扩展性约束）
业务规则（领域逻辑、验证规则、约束条件）
外部问题追踪工具（Linear、Jira、GitHub Issues、ClickUp等）——若团队正在使用
Agent的行为偏好（见步骤4的询问内容）

Workflow

工作流程

1. Analyze existing repo

1. 分析现有仓库

Read
```
package.json
```
, config files, directory structure
Identify tech stack, package manager, existing scripts
Check for existing AGENTS.md, CLAUDE.md, docs/
Note what's already discoverable from source (don't re-document it)

读取
```
package.json
```
、配置文件、目录结构
识别技术栈、包管理器、现有脚本
检查是否已存在AGENTS.md、CLAUDE.md、docs/目录
记录哪些内容已可从源码中获取（无需重复记录）

2. Create or convert

docs/REQUIREMENTS.md

and

docs/BUSINESS-RULES.md

2. 创建或转换

docs/REQUIREMENTS.md

和

docs/BUSINESS-RULES.md

If these files already exist, ask the user whether to convert them to the status-based format. Preserve all existing content — only restructure the format and add status fields. If creating from scratch, interview user or extract from existing code.

Choose the correct template based on whether the team uses an external tracker:

如果这些文件已存在，询问用户是否要将其转换为基于状态的格式。保留所有现有内容——仅调整格式并添加状态字段。如果从头创建，则与用户沟通或从现有代码中提取信息。

根据团队是否使用外部追踪工具选择正确的模板：

Solo mode (no external tracker)

独立模式（无外部追踪工具）

Status lives in the doc. Single source of truth = docs.

markdown

undefined

状态信息保存在文档中。唯一可信来源 = 文档。

markdown

undefined

Requirements

需求

Status Reference

状态参考

Status	Meaning
`draft`	Written but not yet reviewed — may be vague or incomplete
`refined`	Reviewed and clarified by user, ready to implement
`in-progress`	Actively being implemented by the agent
`implemented`	Code written by agent, awaiting user review
`verified`	User reviewed and approved — only the user sets this
`deferred`	Intentionally postponed, not abandoned
`cancelled`	No longer relevant, kept for historical context

状态	含义
`draft`	已撰写但尚未审核——可能模糊或不完整
`refined`	已由用户审核并明确，可开始实现
`in-progress`	Agent正在积极实现中
`implemented`	Agent已完成代码编写，等待用户审核
`verified`	用户已审核并批准——仅可由用户设置此状态
`deferred`	有意推迟，未被放弃
`cancelled`	不再相关，仅保留历史记录

Functional Requirements

功能需求

[Feature Area]

[功能领域]

FR-001: [Requirement title]

FR-001: [需求标题]

Status:
```
draft
```
Description: [What the system should do]

undefined

状态:
```
draft
```
描述: [系统应实现的功能]

undefined

Team mode (external tracker: Linear, Jira, GitHub Issues, etc.)

团队模式（使用外部追踪工具：Linear、Jira、GitHub Issues等）

**Status**:

field in docs — status lives in the tracker. Single source of truth = tracker. The

**Issue**:

field links to the tracker item.

markdown

undefined

文档中不包含

**Status**:

字段——状态信息保存在追踪工具中。唯一可信来源 = 追踪工具。

**Issue**:

字段链接到追踪工具中的条目。

markdown

undefined

Requirements

需求

Functional Requirements

功能需求

[Feature Area]

[功能领域]

FR-001: [Requirement title]

FR-001: [需求标题]

Issue: (none yet)
Description: [What the system should do]


When `**Issue**:` is `(none yet)`, the agent creates the issue in the tracker
and writes back the ID (e.g., `LINEAR-123`, `PROJ-42`, `#123`).

Structure for `docs/BUSINESS-RULES.md` (same pattern in both modes):

```markdown

Issue: (none yet)
描述: [系统应实现的功能]


当`**Issue**:`为`(none yet)`时，Agent需在追踪工具中创建问题，并将ID（如`LINEAR-123`、`PROJ-42`、`#123`）写回文档。

`docs/BUSINESS-RULES.md`的结构（两种模式下格式相同）：

```markdown

Business Rules

业务规则

[Domain Area]

[领域范围]

BR-001: [Rule name]

BR-001: [规则名称]

Status:
```
draft
```
← solo mode
Issue: (none yet) ← team mode (use one, not both)
When: [Trigger condition]
Then: [Expected behavior]
Rationale: [Why this rule exists]


Keep requirements specific, testable, and numbered for traceability.

Status:
```
draft
```
← 独立模式
Issue: (none yet) ← 团队模式（二选一）
触发条件: [触发场景]
预期行为: [执行后的结果]
规则依据: [该规则存在的原因]


需求需具体、可测试，并编号以确保可追溯性。

Agent Workflow for Requirements & Business Rules

需求与业务规则的Agent工作流

Solo mode lifecycle:

Draft — user or agent adds a new item with
```
status: draft
```
Refine — agent clarifies until specific and testable; user confirms; status →
```
refined
```
Implement — user asks agent to implement a specific ID; agent implements it and updates status →
```
implemented
```
Verify — user reviews; if approved, status →
```
verified
```
; if rejected, status →
```
in-progress
```
with a note

The agent must never set status to

verified

— only the user does. The agent must update status to

implemented

before closing a session.

Team mode lifecycle (tracker integration):

When bulk-creating issues from requirements, follow the pre-flight checklist and patterns in references/tracker-issue-patterns.md.

When asked to implement a requirement:

Check
**Issue**:
field
- If
```
(none yet)
```
  → create an issue in the tracker via MCP (title = requirement title, description = requirement body), write back the ID
- If an ID exists → query the tracker for current status before proceeding
Check tracker status
- If
```
in-progress
```
  (or equivalent) → warn the user and stop. Do not proceed silently. The user decides whether to continue, reassign, or skip.
- Otherwise → transition to in-progress in the tracker, then implement
After implementation → transition tracker status to the equivalent of
```
implemented
```
/
```
done
```
(discover available statuses via MCP; infer the mapping — do not hardcode it)
Never query all requirements at session start — query only the specific item being worked on (lazy query)

独立模式生命周期：

草稿——用户或Agent添加新条目，状态设为
```
draft
```
细化——Agent将需求明确至具体可测试；用户确认后，状态更新为
```
refined
```
实现——用户要求Agent实现特定ID的需求；Agent完成实现后将状态更新为
```
implemented
```
验证——用户审核；若批准，状态更新为
```
verified
```
；若拒绝，状态更新为
```
in-progress
```
并添加备注

Agent绝不能将状态设置为

verified

——仅用户可执行此操作。 Agent必须在会话结束前将状态更新为

implemented

。

团队模式生命周期（集成追踪工具）：

从需求批量创建问题时，请遵循references/tracker-issue-patterns.md中的预检清单和模式。

当被要求实现某一需求时：

检查
**Issue**:
字段
- 如果是
```
(none yet)
```
  →通过MCP在追踪工具中创建问题（标题=需求标题，描述=需求内容），并将ID写回文档
- 如果已有ID→在开始前查询追踪工具中的当前状态
检查追踪工具状态
- 如果是
```
in-progress
```
  （或等效状态）→警告用户并停止操作。不得静默继续。由用户决定是否继续、重新分配或跳过。
- 否则→在追踪工具中将状态转换为
```
in-progress
```
  ，然后开始实现
实现完成后→将追踪工具中的状态转换为
```
implemented
```
/
```
done
```
的等效状态（通过MCP查询可用状态；自行推断映射关系——不要硬编码）
会话开始时绝不查询所有需求——仅查询当前正在处理的特定条目（延迟查询）

3. Create context docs per deployment layer (if multi-layer project)

3. 为每个部署层创建上下文文档（如果是多层项目）

For projects with multiple independent layers (backend, frontend, mobile, etc.), create per-layer context docs that track implementation status separately.

See references/multi-layer-guide.md for the full guide: directory structures, context doc rules, monorepo vs separate repo layouts, and agent workflow with layered docs.

对于包含多个独立层（后端、前端、移动端等）的项目，创建每层的上下文文档，分别跟踪实现状态。

完整指南请参阅references/multi-layer-guide.md：目录结构、上下文文档规则、单仓库与多仓库布局，以及使用分层文档的Agent工作流。

4. Generate minimal

AGENTS.md

4. 生成精简的

AGENTS.md

See references/agents-md-guide.md for full principles.

The file must be as small as possible. Only include:

One-sentence project description
Pointers to docs/ with the sync rule (mandatory — without this, the status lifecycle is dead on arrival since agents start fresh every session)
Behavioral instructions (agent workflow preferences that are undiscoverable from source). Ask the user if they have preferences for:
- Plan mode: how agents should present plans (e.g., concise vs detailed, listing unresolved questions)
- Communication style: brevity, formality, language
- Docs lookup: whether agents should consult a documentation retrieval tool (e.g., Context7) before implementing with external libraries, to avoid hallucinating outdated APIs
- Tracker integration: whether the team uses an external issue tracker (Linear, Jira, GitHub Issues, etc.) and agents should create/sync issues automatically when implementing requirements
- Workflow habits: any recurring instructions they find themselves repeating across sessions

Example (single-layer project):

markdown

undefined

完整原则请参阅references/agents-md-guide.md。

该文件必须尽可能精简。仅需包含：

一句话项目描述
指向docs/目录的链接及同步规则（必填——若无此规则，状态生命周期将无法正常运行，因为Agent每次会话都是全新开始）
行为指令（无法从源码中发现的Agent工作流偏好）。询问用户是否有以下偏好：
- 规划模式：Agent应如何呈现规划（如简洁型vs详细型，列出未解决的问题）
- 沟通风格：简洁性、正式程度、语言
- 文档查询：在使用外部库实现功能前，Agent是否应先查阅文档检索工具（如Context7），以避免使用过时的API
- 追踪工具集成：团队是否使用外部问题追踪工具（Linear、Jira、GitHub Issues等），Agent在实现需求时是否应自动创建/同步问题
- 工作流习惯：用户在各会话中重复提及的任何常规指令

示例（单层项目）：

markdown

undefined

Project Name

项目名称

SaaS platform for team retrospectives with real-time collaboration.

支持实时协作的团队回顾SaaS平台。

Docs

文档

```
docs/REQUIREMENTS.md
```
— functional and non-functional requirements
```
docs/BUSINESS-RULES.md
```
— domain rules and constraints

When implementing features or fixing bugs, update the relevant requirement/rule status in these docs to keep them synced with the codebase.

```
docs/REQUIREMENTS.md
```
— 功能与非功能需求
```
docs/BUSINESS-RULES.md
```
— 领域规则与约束

在实现功能或修复Bug时，请更新这些文档中相关需求/规则的状态，以保持与代码库的同步。

Docs Lookup

文档查询

When implementing or fixing bugs involving external libraries, always consult Context7 for up-to-date documentation before writing code. Never rely on training data for library APIs.

在实现或修复涉及外部库的Bug时，编写代码前务必查阅Context7以获取最新文档。绝不要依赖训练数据中的库API。

Plan Mode

规划模式

Make the plan extremely concise. Sacrifice grammar for the sake of concision.
At the end of each plan, give me a list of unresolved questions to answer, if any.


For multi-layer projects, see the
[multi-layer guide](references/multi-layer-guide.md#agentsmd-example) for an
AGENTS.md example.

**Team mode addition** — if the team uses an external tracker, add a Tracker
section to AGENTS.md instead of a Docs sync rule:

```markdown

规划需极度简洁。为了简洁性可适当牺牲语法规范。
在每个规划的末尾，列出所有未解决的问题（如有）。


对于多层项目，`AGENTS.md`示例请参阅[多层指南](references/multi-layer-guide.md#agentsmd-example)。

**团队模式补充**——如果团队使用外部追踪工具，请在AGENTS.md中添加Tracker部分，而非文档同步规则：

```markdown

Docs

文档

```
docs/REQUIREMENTS.md
```
— functional and non-functional requirements
```
docs/BUSINESS-RULES.md
```
— domain rules and constraints

```
docs/REQUIREMENTS.md
```
— 功能与非功能需求
```
docs/BUSINESS-RULES.md
```
— 领域规则与约束

Tracker

追踪工具

Issue tracker: Linear (MCP available in this session).

When implementing a requirement:

If
```
**Issue**:
```
is
```
(none yet)
```
, create an issue and write back the ID.
If an ID exists, query the tracker for current status before proceeding.
If status is in-progress, warn the user and stop — do not proceed silently.
Discover available statuses via MCP; infer the mapping — do not hardcode it.
Never query all requirements at session start — query only what you're about to work on.

When bulk-creating issues from requirements, follow the pre-flight checklist in

references/tracker-issue-patterns.md

before creating anything.


Replace `Linear` with the actual tracker. Remove the "MCP available" note if
the team doesn't use an MCP integration for that tracker.

**Do NOT include**: package manager (discoverable from lock files,
`packageManager` field in `package.json`, or enforcement hooks), commands
(discoverable from `package.json` scripts), architecture descriptions, file
listings, framework/library explanations, implementation patterns. These are all
discoverable from source.

问题追踪工具：Linear（本次会话中MCP可用）。

在实现需求时：

如果
```
**Issue**:
```
为
```
(none yet)
```
，请创建问题并将ID写回文档。
如果已有ID，请在开始前查询追踪工具中的当前状态。
如果状态为
```
in-progress
```
，请警告用户并停止操作——不得静默继续。
通过MCP查询可用状态；自行推断映射关系——不要硬编码。
会话开始时绝不查询所有需求——仅查询当前即将处理的条目。

从需求批量创建问题时，请在创建前遵循

references/tracker-issue-patterns.md

中的预检清单。


将`Linear`替换为实际使用的追踪工具。如果团队未使用该追踪工具的MCP集成，请移除“MCP可用”的备注。

**请勿包含**：包管理器（可从锁文件、`package.json`中的`packageManager`字段或强制执行钩子中获取）、命令（可从`package.json`的scripts中获取）、架构描述、文件列表、框架/库说明、实现模式。这些内容均可从源码中获取。

5. Create

CLAUDE.md

symlink

5. 创建

CLAUDE.md

符号链接

bash

ln -s AGENTS.md CLAUDE.md

This keeps Claude Code and other tools reading the same instructions.

bash

ln -s AGENTS.md CLAUDE.md

此操作可确保Claude Code和其他工具读取相同的指令。

6. Set up feedback loops (optional)

6. 设置反馈循环（可选）

See references/feedback-loops.md for details.

Ask user which feedback loops to set up:

TypeScript
```
type-check
```
script in package.json
Test runner (
```
vitest
```
,
```
jest
```
,
```
bun test
```
)
E2E tests (
```
playwright
```
,
```
cypress
```
) — for frontend projects
Pre-commit hooks: Lefthook (recommended) or Husky + lint-staged
Code quality: Oxlint + Oxfmt (recommended), Biome, or ESLint + Prettier

Pre-commit hooks are the most powerful feedback loop for AI agents — they get error messages on failed commits and retry automatically.

详情请参阅references/feedback-loops.md。

询问用户要设置哪些反馈循环：

在package.json中添加TypeScript
```
type-check
```
脚本
测试运行器（
```
vitest
```
、
```
jest
```
、
```
bun test
```
）
E2E测试（
```
playwright
```
、
```
cypress
```
）——针对前端项目
预提交钩子：Lefthook（推荐）或Husky + lint-staged
代码质量工具：Oxlint + Oxfmt（推荐）、Biome，或ESLint + Prettier

预提交钩子是对AI Agent最强大的反馈循环——它们会在提交失败时收到错误信息并自动重试。

7. Set up deterministic enforcement (optional)

7. 设置确定性强制执行机制（可选）

See references/deterministic-enforcement.md for details.

Ask user which agent tools they use and set up enforcement for each:

Claude Code:
```
PreToolUse
```
hooks in
```
.claude/settings.json
```
(bash scripts)
OpenCode: plugins in
```
.opencode/plugins/
```
(TypeScript/JavaScript modules)

Ask about both tools — users may use one or both. Set up enforcement for every tool the user opts into.

Common enforcement rules:

Enforce correct package manager (block
```
npm
```
,
```
yarn
```
,
```
bun
```
,
```
deno
```
if using
```
pnpm
```
)
Block dangerous git commands (
```
git push --force
```
,
```
git reset --hard
```
)
Block specific CLI patterns
Protect sensitive files (
```
.env
```
, credentials)

Enforcement saves instruction budget and is deterministic — rules cannot be ignored by the agent. It also makes the package manager discoverable by agents (they see the error message when blocked), which is why it doesn't need to be in AGENTS.md.

详情请参阅references/deterministic-enforcement.md。

询问用户使用哪些Agent工具，并为每个工具设置强制执行机制：

Claude Code:
```
.claude/settings.json
```
中的
```
PreToolUse
```
钩子（bash脚本）
OpenCode:
```
.opencode/plugins/
```
中的插件（TypeScript/JavaScript模块）

询问两种工具——用户可能使用其中一种或两种。为用户选择的所有工具设置强制执行机制。

常见强制执行规则：

强制使用正确的包管理器（如果使用
```
pnpm
```
，则阻止
```
npm
```
、
```
yarn
```
、
```
bun
```
、
```
deno
```
）
阻止危险的git命令（
```
git push --force
```
、
```
git reset --hard
```
）
阻止特定的CLI模式
保护敏感文件（
```
.env
```
、凭据）

强制执行机制可节省指令成本，且具有确定性——Agent无法忽略规则。它还能让Agent发现包管理器（当被阻止时会看到错误信息），因此无需在AGENTS.md中提及。

Deliverables

交付成果

```
docs/REQUIREMENTS.md
```
— numbered functional + non-functional requirements (definitions only)
```
docs/BUSINESS-RULES.md
```
— numbered business rules with triggers/behavior (definitions only)
```
docs/[layer]/REQUIREMENTS.md
```
— per-layer status + implementation scope (if multi-layer)
```
docs/[layer]/BUSINESS-RULES.md
```
— per-layer enforcement status (if multi-layer)
```
AGENTS.md
```
— minimal, hand-crafted, globally relevant only
```
CLAUDE.md
```
— symlink to AGENTS.md
Feedback loops configured (if opted in)
Deterministic enforcement configured (if opted in)

```
docs/REQUIREMENTS.md
```
— 编号的功能+非功能需求（仅定义）
```
docs/BUSINESS-RULES.md
```
— 带触发条件/行为的编号业务规则（仅定义）
```
docs/[layer]/REQUIREMENTS.md
```
— 每层的状态+实现范围（如果是多层项目）
```
docs/[layer]/BUSINESS-RULES.md
```
— 每层的强制执行状态（如果是多层项目）
```
AGENTS.md
```
— 精简、手工编写、仅包含全局相关内容
```
CLAUDE.md
```
— 指向AGENTS.md的符号链接
已配置的反馈循环（如果用户选择）
已配置的确定性强制执行机制（如果用户选择）

Anti-patterns to avoid

需避免的反模式

Bloated AGENTS.md — every line costs tokens on every session
Documenting the discoverable — agents read
```
package.json
```
scripts, lock files (
```
pnpm-lock.yaml
```
,
```
yarn.lock
```
, etc.),
```
packageManager
```
field, config files, and imports. Don't repeat what they'll find in seconds.
Listing package manager or commands — discoverable from lock files,
```
packageManager
```
field in
```
package.json
```
, and enforcement hooks
File path references — paths change; describe capabilities instead
Auto-generated init files — stale immediately, actively mislead agents
Global rules for local concerns — use progressive disclosure or skills instead
Missing docs sync rule — without telling agents to update requirement/rule statuses, the entire lifecycle system is unused
Layer status in root docs — when using layered docs, agents must not update the root doc status to reflect only their own layer's progress. Root status is aggregated (all layers done → root promoted). Updating it prematurely misleads other layers into thinking the feature is complete across the whole system.
Dual source of truth for status — in team mode, never put
```
**Status**:
```
in docs alongside
```
**Issue**:
```
. The tracker is the single source of truth. Keeping both leads to divergence and confusion about which one is authoritative.

臃肿的AGENTS.md——每一行内容都会在每次会话中消耗令牌
记录可发现的内容——Agent会读取
```
package.json
```
脚本、锁文件（
```
pnpm-lock.yaml
```
、
```
yarn.lock
```
等）、
```
package.json
```
中的
```
packageManager
```
字段、配置文件和导入语句。不要重复它们在几秒内就能找到的内容。
列出包管理器或命令——可从锁文件、
```
package.json
```
中的
```
packageManager
```
字段和强制执行钩子中获取
文件路径引用——路径会变化；应描述功能而非路径
自动生成的初始化文件——会立即过时，甚至会误导Agent
针对局部问题的全局规则——使用渐进式披露或技能替代
缺失文档同步规则——如果不告知Agent更新需求/规则状态，整个生命周期系统将无法生效
根文档中的层状态——使用分层文档时，Agent不得仅根据自身层的进度更新根文档的状态。根状态是所有层的汇总（所有层完成→根状态升级）。过早更新会误导其他层认为功能已在整个系统中完成。
状态的双重可信来源——在团队模式下，绝不要在文档中同时设置
```
**Status**:
```
和
```
**Issue**:
```
。追踪工具是唯一的可信来源。同时保留两者会导致信息不一致，并让用户困惑哪个是权威来源。

ai-repo-setup

Original

Translation

AI Repo Setup

AI代码仓库配置

Inputs to gather (if missing)

需要收集的输入信息（若缺失）

Workflow

工作流程

1. Analyze existing repo

1. 分析现有仓库

2. Create or convert docs/REQUIREMENTS.md and docs/BUSINESS-RULES.md

2. 创建或转换docs/REQUIREMENTS.md和docs/BUSINESS-RULES.md

Solo mode (no external tracker)

独立模式（无外部追踪工具）

Requirements

需求

Status Reference

状态参考

Functional Requirements

功能需求

[Feature Area]

[功能领域]

FR-001: [Requirement title]

FR-001: [需求标题]

Team mode (external tracker: Linear, Jira, GitHub Issues, etc.)

团队模式（使用外部追踪工具：Linear、Jira、GitHub Issues等）

Requirements

需求

Functional Requirements

功能需求

[Feature Area]

[功能领域]

FR-001: [Requirement title]

FR-001: [需求标题]

Business Rules

业务规则

[Domain Area]

[领域范围]

BR-001: [Rule name]

BR-001: [规则名称]

Agent Workflow for Requirements & Business Rules

需求与业务规则的Agent工作流

3. Create context docs per deployment layer (if multi-layer project)

3. 为每个部署层创建上下文文档（如果是多层项目）

4. Generate minimal AGENTS.md

4. 生成精简的AGENTS.md

Project Name

项目名称

Docs

文档

Docs Lookup

文档查询

Plan Mode

规划模式

Docs

文档

Tracker

追踪工具

5. Create CLAUDE.md symlink

5. 创建CLAUDE.md符号链接

6. Set up feedback loops (optional)

6. 设置反馈循环（可选）

7. Set up deterministic enforcement (optional)

7. 设置确定性强制执行机制（可选）

Deliverables

交付成果

Anti-patterns to avoid

需避免的反模式

2. Create or convert
`docs/REQUIREMENTS.md`
and
`docs/BUSINESS-RULES.md`

2. 创建或转换
`docs/REQUIREMENTS.md`
和
`docs/BUSINESS-RULES.md`

4. Generate minimal
`AGENTS.md`

4. 生成精简的
`AGENTS.md`

5. Create
`CLAUDE.md`
symlink

5. 创建
`CLAUDE.md`
符号链接