# AGENT.md - AI Agent 开发规范

## 开发流程

### 1. 梳理需求

使用 brainstorming 进行头脑风暴, 文档存放与命名规则如下:

| 需求类型 | 计划目录          | 命名规则              | 示例                    |
| -------- | ----------------- | --------------------- | ----------------------- |
| 新功能   | `plans/feature/`  | `xxx-xxx-feature.md`  | `smart-view-feature.md` |
| 修 Bug   | `plans/fix/`      | `xxx-xxx-fix.md`      | `token-refresh-fix.md`  |
| 重构     | `plans/refactor/` | `xxx-xxx-refactor.md` | `api-split-refactor.md` |

使用 writing-plans 技能制定实施计划

**开发新功能时必须评估权限需求**：每个新功能/新操作都需要考虑是否需要纳入权限控制。具体评估方式见下方「权限系统」章节。

可参考的开发文档位于 `docs/dev/*`

### 2. 建立开发分支

确定好需求之后，就使用 `enterprise-git-spec` 技能来建立分支。

### 3. 按照需求开发

按照当前功能的计划文档的任务项及其任务细节来逐步实现功能, 全程严格地遵循技能 test-driven-development 进行 TDD 开发流程, 并遵循 executing-plans 技能来执行开发计划。

**重要原则：所有测试必须通过**

- 开发过程中，必须确保所有测试用例都通过，包括新功能的测试和现有功能的测试
- 如果发现现有测试失败，必须立即修复，确保新功能不会破坏旧功能
- 只有在所有测试都通过的情况下，才能认为开发完成

所有任务完成后请遵循 verification-before-completion 技能完成验证

### 4. 合并到开发分支

所有测试通过后，使用 `enterprise-git-spec` 技能提交分支，然后合并回 `develop` 分支。

### 5. 沉淀开发经验

在实现功能过程中，将适用于任何项目的编码好想法、好思想、注意点等有助于项目推进的内容，及时追加到 `AGENT.md` 中。这些经验是跨功能、跨项目的通用知识，帮助后续开发少走弯路。

### 6. 更新项目结构文档

每次功能开发完成后，更新 `docs/references/structs.md` 文件。该文件记录整个项目的目录结构和每个模块的简要功能描述，便于每次迭代功能时快速理解整个项目全貌。

### 7. 更新使用文档

使用文档分为：

1. `README.md` - 面向人类使用者，帮助其快速上手项目。仅在新功能开发完成后更新。内容保持简洁，聚焦于让用户快速跑通基础流程。
2. `docs/references/*` - 面向人类使用者，提供项目的全面使用指南，支持深度探索模块与命令行细节。每次新功能开发完成或已有功能调整后必须更新。示例要丰富，帮助使用者理解各项功能的具体用法。
3. `skills/[项目名]/SKILL.md` - 面向 LLM / AI Agent，指导大模型如何使用本项目。

**快速开始文档**每次新功能开发完成后才更新，具体更新 `README.md` 文件。确保文档包含新增功能的使用示例、命令说明和注意事项，帮助用户快速上手。

**详细使用文档**位于 `docs/references/*`，目录文件为 `docs/references/index.md`，请按照功能划分参考文档，并填充详细的使用说明，帮助用户深度探索模块/命令行的使用。每次新功能或旧功能调整了请更新最新的使用方法，例子应该丰富一些，便于使用者理解功能使用。

**AGENT使用技能文档**位于 `skills/[项目名]/*`，入口文件为 `skills/[项目名]/SKILL.md`，更新时机和要求与详细使用文档一致。

## 开发规范

### 代码优化

遵循 improve-codebase-architecture

### 类型规范

参考技能 typescript-advanced-types

### 测试规范

参考技能 javascript-testing-patterns

### 测试

每个任务目录应有对应的测试文件 `test/sync/tasks/<task-name>/handler.test.ts`。

## 数据库设计

PostgreSQL 最佳设计实践: postgresql-table-design 技能
PostgreSQL 最佳性能调优实践: supabase-postgres-best-practices 技能
Prisma Postgres 最佳实践: prisma-postgres 技能

### 后端规范

参考 nestjs-best-practices 技能

> 你可以自己增加规范
