# AGENTS.md 模板

只复制符合项目工作流级别的块。模板默认使用英文，便于多数 coding agent 稳定执行；团队可按需翻译。

## Level 映射

| Level | 复制这些块 |
|---|---|
| Level 1 最小 | 基础块 |
| Level 2 标准 | 基础块 + 规格层 + 执行纪律 + 外部操作安全 |
| Level 3 完整 | Level 2 + 专家审查；只有实际使用时才加入工具底座 |

## 基础块

```markdown
# AI Project Workflow

## Project Rules

Before changing code, inspect the existing project structure and follow local patterns.

Do not perform unrelated refactors, formatting churn, dependency upgrades, or broad cleanup unless explicitly requested.

If scope needs to expand, stop and explain why before continuing.

## Verification

Before completion, run the relevant checks and report the commands and results.

Project commands:

- Install dependencies: `<fill in>`
- Run tests: `<fill in>`
- Run lint/typecheck: `<fill in>`
- Build: `<fill in>`
- Run E2E/browser checks: `<fill in>`

## Completion Criteria

A task is complete only when:

- the requested behavior is implemented
- relevant checks pass or failures are clearly explained
- user-facing behavior is verified when applicable
- no unrelated changes were introduced
- the final response reports what changed and what was verified
```

## 规格层

```markdown
## Spec Layer

For non-trivial feature, behavior, architecture, data, automation, or user-facing changes, create or update a written change artifact before implementation.

The change artifact should describe:

- why the change is needed
- what behavior changes
- important design decisions
- implementation tasks
- verification criteria

If a spec/change artifact already exists, use it as the source of truth. Do not create a separate competing plan unless explicitly requested.
```

## 执行纪律

```markdown
## Agent Discipline

Use disciplined engineering workflow:

- clarify ambiguous requirements before implementation
- prefer test-first or TDD for features and bug fixes
- debug from root cause, not symptoms
- review diffs before calling work complete
- verify behavior with tests, browser checks, logs, screenshots, or reproducible commands

Do not claim completion without evidence.
```

## 专家审查

```markdown
## Specialist Review

Use specialist review only when the project risk justifies it.

Recommended gates:

- product/scope review before large user-facing work
- engineering/design review before complex implementation
- code review after implementation
- QA/browser verification for critical user flows
- security review for auth, permissions, user data, payments, scraping, publishing, or third-party automation
- release review before production deployment

If a spec/change artifact exists, specialist review should improve that artifact, not replace it with a second plan.
```

## 外部操作安全

```markdown
## External Action Safety

Treat networked and external actions as approval-required unless the user explicitly authorizes them.

Ask before:

- pushing commits
- opening or merging PRs
- deploying
- modifying production data
- posting or sending messages
- changing credentials
- running paid jobs
- operating real third-party accounts

Do not send private code, customer data, secrets, production logs, database exports, or credentials to untrusted agents, MCP servers, browser automation, or external services.

For high-risk flows, produce a local plan or report first.
```

## 工具底座

```markdown
## Harness and Tooling Packs

If this project uses a broader AI tooling pack with skills, hooks, rules, MCP servers, or memory features:

- preserve existing project rules
- install only the components this project needs
- avoid duplicate rules from multiple packs
- document what was installed and why
- require maintainer approval before enabling hooks or external-action automation
```

## 完整示例：中型 Web App

```markdown
# AI Project Workflow

## Project Rules

Before changing code, inspect the existing project structure and follow local patterns.

Do not perform unrelated refactors, formatting churn, dependency upgrades, or broad cleanup unless explicitly requested.

If scope needs to expand, stop and explain why before continuing.

## Spec Layer

For non-trivial feature, behavior, architecture, data, automation, or user-facing changes, create or update a change artifact under `docs/changes/` before implementation.

If a change artifact already exists, use it as the source of truth. Do not create a separate competing plan unless explicitly requested.

## Agent Discipline

- clarify ambiguous requirements before implementation
- write tests before or alongside code for features and bug fixes
- debug from root cause, not symptoms
- review the diff before calling work complete
- do not claim completion without evidence

## Verification

Before completion, run the relevant checks and report the commands and results.

Project commands:

- Install dependencies: `pnpm install`
- Run tests: `pnpm test`
- Run lint/typecheck: `pnpm lint && pnpm typecheck`
- Build: `pnpm build`
- Run E2E/browser checks: `pnpm test:e2e`

## External Action Safety

Ask before pushing commits, opening or merging PRs, deploying, or modifying production data.

Do not send private code, customer data, secrets, production logs, database exports, or credentials to untrusted agents, MCP servers, browser automation, or external services.

## Completion Criteria

A task is complete only when:

- the requested behavior is implemented
- relevant checks pass or failures are clearly explained
- user-facing behavior is verified when applicable
- no unrelated changes were introduced
- the final response reports what changed and what was verified
```