Imported from shell909090/ai (tgbot/AGENTS.md). Install upstream with npx skills add shell909090/ai --skill tgbot. Copyright stays with the author.

流程规范

1. 检查git是否有未提交内容，包括stage区和工作区文件；如有，必须由用户明确是提交还是忽略。
2. 获取需求，来源可以是用户口头提出或需求文档。通过git判断需求是首次提出还是变更；如有不明确之处，要求用户澄清补充。口头提出的需求，需要确认是否补充到req.md。
3. 根据需求整理任务并写入tasks.md。每个任务必须包含：唯一ID、描述、状态、达成条件、依赖顺序、交付物。任务状态仅允许 todo、doing、blocked、done。初始状态只能为todo或blocked。允许的状态转换只有：todo<->doing、doing->blocked、doing->done、blocked->todo，其他转换均禁止。依赖顺序必须引用其他任务的唯一ID，避免插入任务时序号变化。涉及多个功能时，任务必须拆开逐个完成；修完一个功能再做下一个。每次git提交都必须保持代码可执行。每个task的达成条件必须可检查；实现完成后，需逐条核对达成条件，未满足项必须写入review.md。
4. 选择tasks.md中第一个状态为todo的任务，结合用户需求和任务定义重新审视设计；如设计变化，更新design.md。design.md只记录设计要点，如数据库结构、重要接口定义、重点业务逻辑，不写无关细节；其中接口定义必须完整精确。设计完成后暂停，等待用户确认。
5. 按任务要求和设计实现代码；如需更新测试，也一并实现。实现应尽量并行，例如前后端并行。在设计已定义接口隔离的前提下，不同组件应拆分给不同subagent；业务代码与测试代码只要条件允许，必须由两个subagent分别实现。若难以直接解耦，可先定义函数签名，再分别实现业务代码和测试代码。所有代码都必须遵循质量规范。
6. 运行代码质量检查工具。每次修改代码，包括测试代码，都必须运行。
7. 运行unittest。如有问题，可以修改设计或代码，但禁止通过修改测试来回避问题。测试必须以需求和设计为依据，不能为了让当前实现通过而改测试。每次修改代码后都必须重新测试。
8. review代码修改，确认逻辑正确。检查当前阶段是否存在未实现功能、安全问题、未清理的调试代码或代码质量问题。如有，按优先级写入review.md。每个问题必须包含唯一ID、重要性评估、问题描述、原因描述和状态。状态仅允许open、suspended、fixed、wontfix、notissue。随后等待用户检查；用户可将问题标记为suspended、wontfix、notissue，或补充新问题。review需要识别技术债，避免把不必要的维护成本留给后续开发和后续AI。
9. 读取更新后的review.md，将需要修复的问题加入tasks.md，并插入头部。原任务标记为blocked，并依赖新加入的bug修复任务。随后重走流程4-8。
10. 修复完成后，将review.md中的问题标记为fixed，将tasks.md中的对应任务标记为done。tasks.md中依赖已全部完成的任务标记为todo，然后回到4继续执行。如此循环直到问题全部解决。若同一问题循环三轮仍无法解决，必须重新审视设计；若仍找不到原因，则询问用户意见。
11. 部署并运行项目进行测试，检查输出日志是否正常。若存在smoke test脚本，则运行检验。若可以驱动测试工具，例如浏览器，则简单实际使用项目。若行为与预期不一致，检查日志并修复问题；做法是把问题加入review.md、把任务加入tasks.md，然后重走流程4-10。
12. 更新README.md和README.cn.md。内容必须包含项目简介、安装和运维说明、使用说明、作者、版权声明和授权协议；其中作者、版权声明和授权协议如不确定，可以询问用户，不得瞎编。
13. 评估tasks.md是否已空，以及用户需求是否已完成。若未完成，把剩余事项写入tasks.md，再按顺序从第4步继续循环。回到第4步前，若当前代码已处于“所有bug均已修正”的可运行状态，则先git stage并提交，再执行下一个任务。git stage前必须先确认哪些文件不应进入git，并调整.gitignore；特别注意tasks.md、review.md、log.md、.env不得进入git。若本轮任务已全部完成，则进入步骤14。
14. 整理本轮文档。将review.md中所有fixed、wontfix、notissue问题归档到log.md并从review.md删除，保留open和suspended问题；将tasks.md中所有done任务归档到log.md并从tasks.md删除。若仍有未提交内容，则git stage并提交。将本轮重点过程追加到log.md。log.md需要记录本轮用户需求、测试发现并修复了哪些问题、覆盖率多少，以及review发现并修复了哪些问题。
15. 最后输出总结：是否完成用户需求，派生了几个task及其当前状态，review出现了几个问题及其当前状态，目前代码覆盖率各是多少。

文件规范

• AGENTS.md：项目规范文档，说明项目如何开发及文件位置，AI禁止修改。
• README.md：项目说明，由AI维护，写给人类阅读，使用英文；英文说明中必须包含其他语言说明的链接。
• README.cn.md：项目中文说明。
• .env：项目启动所需环境变量，禁止加入git。
• docs/req.md：需求文档，用户写给AI看；未经用户明确指示，AI不得修改。
• docs/tasks.md：任务文档，记录当前未完成任务，由AI维护，不加入git。
• docs/design.md：设计文档，AI写给系统维护者看，使用中文。
• docs/review.md：评审文档，由AI和用户共同维护，使用中文，不加入git。
• docs/log.md：运行日志，记录需要保留的重要过程，由AI维护，使用中文并带时间，不加入git。
• frontend/：前后端分离时存放前端代码。
• backend/：前后端分离时存放后端代码。

代码规范

• 代码和注释使用英文；一般文档使用中文，README.md除外。
• git commit message使用英文，要求简明扼要，禁止把AI列为co-author。
• 流程由Makefile统一控制。
• 代码质量检测使用make fmt、make lint、make build。
• 代码测试使用make unittest、make test。
• 测试覆盖率底线为50%，一般目标为75%；分模块覆盖率不得低于50%，低于50%必须警告用户；总体覆盖率低于75%时应尽力提升。
• 若覆盖率确实无法提升，询问用户如何处理：引入外部依赖，或在review.md中保留问题。
• 测试用例必须严格依据文档，不得受实现影响。
• 代码关键处可加注释帮助理解，但不得机械描述代码行为。
• logging系统必须支持调试开关，调试信息使用调试级别输出。
• 如条件允许，优先使用docker进行部署。

前端规范

• 强制使用TypeScript，尽量不用any；确需使用时必须通过注释说明原因，并尽量缩小作用域。
• 优先使用ES6+语法。
• 优先复用项目现有技术栈、目录结构、组件风格和状态管理方式，不要无故新增模式。
• 页面负责组装，复杂逻辑下沉到独立模块，不要在页面或 JSX 中堆过多业务逻辑。
• 接口请求统一封装，禁止在多个页面重复手写请求逻辑。
• 表单、异步请求、错误处理必须有基本反馈，禁止无 loading、无 error、无 empty state。
• 不要提交调试代码，如 console.log、临时 mock、无用样式和注释。

python规范

• 强制使用Type Annotations。
• 公有函数必须包含简洁Docstring，不超过一行，说明核心功能。
• Python环境使用uv管理。
• 静态检查使用ruff，并在make lint中配置McCabe复杂度阈值为10。
• 删除无用代码和无效import。
• 使用logging处理日志。
• 使用py_compile在make build中检查语法。

golang规范

• Go代码必须使用gofmt格式化，并使用goimports处理导入分组；这两项在make fmt中执行。
• Go代码提交前必须通过go test和golangci-lint，分别在make test和make lint中执行。
• 导出符号必须有简洁注释，说明用途。
• 错误必须显式处理，禁止无原因忽略返回的error。如需忽略写注释。

测试手段

• 前端测试可直接使用后端服务作为mock承接；后端应支持mock模式，以提供mock数据或绕过高频接口的熔断限制。
• smoke test可使用无头浏览器，或通过Chrome DevTools Protocol直接驱动用户提供的浏览器。