# Neutron 工程手册

> 这是我们用 AI agent 开发软件的规则。在客户项目上，以客户明确提出的要求为准。

从这里开始: [上手项目](/zh/new-project/). 在项目上做第一个 ticket：弄懂流程，在本地跑起来，选好分支。 刚开始用 AI agent 写代码？先读[用 AI agent 开发](/zh/agent-development/)。

## 规则

1. **代码由 agent 写，不由人写。** 我们用 Claude Code 和 Codex 开发。工程师划定范围、给 agent 提供上下文、检查证据，并对结果负责。不要手工改代码：让 agent 去改；反复出现的错误，写进测试或指令。
2. **一个 ticket，一个目的。** agent 从 ticket 的目标和验收标准出发，PR 只包含实现这个目标所必需的改动。PR 大一点没关系，只要它只做一件事，而且证据够别人核查。把新功能、重构和顺手修复混在一起的 PR 就不行。PR 描述要写明为什么改。
3. **agent 的上下文必须准确。** 每个 agent 都依据 `AGENTS.md`、`CLAUDE.md` 和文档工作，所以文档写错比没写更糟。哪个 PR 让某条指令不再准确，就在同一个 PR 里更新这条指令；计划和工作笔记放在 PR 或 ticket 里，不放进仓库。每次发布后，让文档和代码对齐：该改的改，该补的补，该重组的重组，没人说得清用途的删掉。与其再写一段说明，不如加一个测试或强制检查。
4. **检查通过，要能证明改动符合预期。** 拿出证据，证明每条验收标准都已满足，受影响的现有行为也仍然正常：按验收标准编写测试；测试覆盖不到的地方，实际跑一遍。证据只对执行检查时的那个 commit 有效：代码一改，就要重新收集。写明哪些没有验证。删除、跳过、放宽或禁用检查，都要说明理由，并得到评审人明确同意。
5. **改动要有负责人，合并前要由另一人批准。** 负责人能说清改动做了什么、会怎么出问题、怎么撤销。合并前由另一个人批准。AI 评审只提建议，不能批准。
6. **用权限和工具限制 agent 的操作。** 只有经过批准的工具才能接触我们的代码。绝不把密钥或真实个人数据写进源代码、prompt 或日志。不管 agent 以什么方式运行，生产环境操作和破坏性操作都要有人明确同意。这些边界靠权限和工具强制执行；只写一条指令，不算边界。

## 任务清单

- **我要提交 PR:** PR-1, PR-2, PR-5, CI-1, REL-2, API-1, SEC-2, SEC-3
- **我要评审并合并 PR:** AI-3, PR-3, PR-4, PR-6
- **我要修改优惠券、积分或余额:** VAL-1, VAL-2, VAL-3, VAL-4, VAL-5, VAL-6, VCH-1, VCH-T1, VCH-T2, VAL-7, VAL-T3, VAL-T4, VCH-T3
- **我要保护短信和 OTP 发送:** OTP-1, OTP-2, OTP-3, OTP-4, OTP-5, OTP-6, OTP-T1, OTP-T2, OTP-T3, OTP-T4, OTP-T5, OTP-T6, OTP-T7
- **我要批量发放积分或优惠券:** VAL-8, VAL-3, VAL-7, VAL-T1, VAL-T2
- **我要修改数据库结构:** MIG-1, MIG-2, MIG-5, MIG-T1, MIG-T3
- **我要调用外部服务:** EXT-1, VAL-6, EXT-T1, EXT-T2
- **我要新增或修改后台任务:** JOB-1, JOB-2, JOB-3, EXT-1, JOB-T1, JOB-T2, JOB-T3, JOB-T4, JOB-T5
- **我要上线营销活动:** VAL-7, CMP-1, CMP-2, CMP-3, CMP-4
- **我要把工作交给 AI agent:** AI-1, AI-2, AI-3, PR-4
- **我要发布新版本:** REL-1, REL-2, REL-3, REL-4, REL-8, REL-5, REL-6, REL-7, API-1
- **我要修改权限或租户范围内的数据:** SEC-1, SEC-3, SEC-T1, SEC-T2
- **我要处理生产环境事故:** INC-1, INC-2, INC-3, AI-2
- **我要准备上线或大版本发布:** SSAT-1, REL-8, REL-5, REL-6