# AGENTS.md 通用模板

> 替换所有 `{{...}}` 占位符为项目实际内容。保持总行数 ≤ 200。

---

## 1. 项目概述

{{一段话说清项目定位、核心价值、技术栈。例如：}}

> {{项目名}} 是 {{做什么的}}，基于 {{技术栈}} 构建。采用 {{架构风格，如前后端分离 / monorepo / 微服务}}，核心模块包括 {{模块 A}}、{{模块 B}}、{{模块 C}}。

**技术栈：** {{语言/框架/数据库/中间件}}

**仓库结构：**

```
{{tree -L 2 的实际输出，或精简版目录树}}
```

## 2. 快速开始

| 操作 | 命令 |
|------|------|
| 安装依赖 | `{{install command}}` |
| 启动开发服务器 | `{{dev start command}}` |
| 构建生产包 | `{{build command}}` |
| 代码格式化 | `{{format command}}` |
| 质量检查 | `{{lint command}}` |
| 运行测试 | `{{test command}}` |

## 3. 系统架构

### 包/模块结构

```
{{关键目录及用途，精简到核心层级}}
```

### API 约定

- {{REST/GraphQL/gRPC 等}}
- {{认证方式}}
- {{错误码规范}}

### 组件规范

- {{核心组件命名约定}}
- {{状态管理方案}}
- {{数据流方向}}

> 详细架构文档 → 见 `docs/ARCHITECTURE.md`

## 4. 代码规范与编程原则

### 代码规范

{{根据项目情况选择以下之一：}}

**选项 A（≥ 10 文件，从代码分析）：**
> 本项目编码规范 → 见 `docs/CODING_STYLE.md`

**选项 B（< 10 文件，社区标准）：**
- **命名约定：** {{根据技术栈引用对应社区规范，如 Effective Go、Airbnb Style Guide 等}}
- **格式化：** {{对应 formatter}}
- **注释要求：** {{对应 doc style}}

### 通用约定

- **Lint 规则：** `{{lint config}}`
- **Git 提交工具：** 优先使用 `git-commit-helper` skill；也可采用社区标准语义化 Git Commit 协议（Conventional Commits）

### 编程原则

> 详见 [references/principles.md](references/principles.md)，生成时直接将以下内容嵌入：
>
> 编程原则示例参见 [references/examples.md](references/examples.md)，建议外链到 `docs/programming-principles-examples.md`。

<!-- 编程原则全文嵌入开始 -->

**权衡：** 这些指导原则倾向于谨慎而非速度。对于琐碎的任务，请自行判断。

#### 编码前先思考

不要妄下断言。不要掩饰困惑。坦诚地权衡利弊。实施前：明确陈述假设，有疑问就提；多种解释时全部列出，不静默选择；有更简单的方法就指出，必要时坚持己见；不清楚时停下来，说出困惑再提问。

#### 简单至上

最少代码解决问题，不做推测。不添加未要求的功能；不为一次性代码做抽象；不提供未请求的「灵活性」或「可配置性」；不对不可能的情况做错误处理。200 行能写成 50 行就重写——问自己「资深工程师会觉得过于复杂吗？」

#### 手术式改动

只碰必须碰的东西，只收拾自己的烂摊子。不改进相邻代码、注释或格式；不重构没问题的代码；匹配既有风格；发现无关死代码时提及但不删除。删除因自己改动造成的孤儿 import/变量/函数，除非被要求否则不删除已有死代码。**标准：** 每行修改都直接追溯到用户请求。

#### 目标驱动型执行

定义成功标准，循环迭代直到验证通过。「添加校验」→先写失败用例再修通；「修 bug」→写复现测试再修复；「重构」→确保前后测试均通过。多步骤任务声明计划：`[步骤] → verify: [检查点]`。

<!-- 编程原则全文嵌入结束 -->

## 5. 本地开发及验证

完整的「改 → 构建 → 启动 → 验证」闭环：

```bash
# 1. 改代码
vim src/xxx

# 2. 格式化 + lint
{{format command}}
{{lint command}}

# 3. 构建
{{build command}}

# 4. 启动
{{start command}}

# 5. 验证
{{test command}}
{{integration test command if any}}
```

## 6. 文档导航

| 文档 | 路径 | 说明 |
|------|------|------|
| 架构设计 | `docs/ARCHITECTURE.md` | 系统架构图、模块职责 |
| 编码规范 | `docs/CODING_STYLE.md` | 详细 lint 规则、命名约定 |
| API 文档 | `docs/api.md` | 接口定义、错误码 |
| 部署指南 | `docs/deployment.md` | 环境配置、发布流程 |
| 故障排查 | `docs/troubleshooting.md` | 常见问题及解法 |

> 按需增删此表，确保索引与实际文档同步。