附录 C：AGENTS.md 模板

将本模板复制到项目根目录的 AGENTS.md，帮助 Coding Agent 理解项目规则。内容应短小、具体、可执行、可验证。

# AGENTS.md

## Project Overview

- Project name: <project-name>
- Business domain: <domain>
- Main responsibility: <what this service does>
- Primary language/runtime: <Java 21 / Node.js / Python ...>
- Framework: <Spring Boot 3.x / ...>

## Repository Structure

```text
src/main/java/...        Main source code
src/test/java/...        Tests
docs/                    Project docs
scripts/                 Utility scripts
```

## Build and Test Commands

- Run all tests:

```bash
./mvnw test
```

- Run one test class:

```bash
./mvnw -Dtest=<ClassName> test
```

- Run one test method:

```bash
./mvnw -Dtest=<ClassName>#<methodName> test
```

## Coding Rules

- Follow existing package structure.
- Do not introduce new framework dependencies without approval.
- Keep domain rules in domain/service layer, not controllers.
- Prefer small, focused changes.

## Testing Rules

- Add or update tests for behavior changes.
- Prefer focused tests before full test suite.
- If a test fails, inspect the failure before changing production code.
- Do not delete failing tests to make CI pass.

## Safety Rules

- Do not modify secrets, credentials, tokens, or production config.
- Do not run destructive commands.
- Ask for approval before write operations if task is read-only.
- Do not push commits or create PRs unless explicitly requested.

## Common Gotchas

- <Example: Changing OrderStatus requires updating OrderStateMachine.allowedTransitions.>
- <Example: CI uses PostgreSQL; local tests may use H2.>
- <Example: Generated files should not be edited manually.>

## Output Requirements

When reporting analysis, include:

- summary;
- evidence;
- files inspected;
- commands/tools used;
- suggested next steps;
- limitations.

编写原则

1. 不写项目百科，只写 Agent 完成任务所需规则。
2. 不写密钥、账号、内网地址等敏感信息。
3. 不写频繁变化的信息，例如临时分支名。
4. 每条规则尽量可执行、可验证。
5. 从 Agent 失败案例中持续更新 Common Gotchas。