AI Coding 编程中值得遵守的简单原则

AI Coding 编程中值得遵守的简单原则

下面是我和kimi一起完善出的几个规则.

适用于中大型关键软件项目。核心思想：AI 负责快，人负责准；AI 的每次输出都要能被验证。

一、任务边界类

1. 范围声明先行：每次会话开头明确写下"本次只修改 X 目录下与 Y 功能相关的代码，不得改动其他文件"。
2. 单一任务原则：一次会话只解决一个问题。复杂重构拆成多个小会话，每步可验证、可回滚。
3. AI 先复述、后动手：要求 AI 先用 3-5 句话复述它理解的任务和约束，确认无误后才允许写代码。

二、验证与交叉验证

4. 双模型交叉评审： 分析/计划/编码/代码评审, 都可以同时交给两个厂商模型来完成, 由人或AI汇总合并两个模型的结果，重点挑逻辑错误和遗漏的边界条件。
5. 测试先于结论：AI 声称"修好了"不算数，必须给出运行测试的命令和实际输出。没有可运行证据的结论一律视为未完成。
6. 破坏性操作需人工确认：删除文件、改数据库结构、改公开 API、改配置类，列清单后由人逐条确认再执行。

三、上下文与知识管理

---

8. Spec 先行且版本化：接口、数据结构、状态机先写进 spec 文档（如 docs/spec/），代码改动前先更新 spec；AI 以 spec 为准绳而非对话记忆。
9. 项目宪法文件：维护一个 CONTRIBUTING.md / AGENTS.md，写明目录结构、命名约定、禁止事项（如禁止引入新依赖需批准）。每次会话让 AI 先读它。
10. 上下文即证据：提问时提供真实代码片段、报错原文、版本号，不要让 AI 凭猜测工作；反过来，AI 给出的关键结论要求它标注依据来自哪份文档/哪个文件。

四、增量与可回滚

11. 小步提交：AI 的改动按逻辑拆成多个小 commit，每步独立可编译、可通过测试，回滚成本低。
12. 先侦察、后实施：大改动前让 AI 先做"只读侦察"（列出影响文件、风险点、备选方案），人确认方案后再进入编码阶段——即影响分析。
13. 不静默改无关代码：指令中明确"禁止顺手重构、格式化、修无关警告"，防止 diff 被噪音淹没，掩盖真实风险。

五、责任与质量门槛

14. 关键逻辑人写或人审：鉴权、资金、并发、数据迁移等核心路径，AI 可以生成初稿，但必须人工逐行审查，不得批量通过。
15. "不知道"比"编一个"好：鼓励 AI 在信息不足时输出"无法确定，需要查看 X 文件"，禁止猜测接口行为或依赖版本。
16. 变更留痕：要求 AI 在 PR 描述中列出：改了什么、为什么改、影响面、验证方式。评审人按此清单核对，而不是通读全部 diff。

六、工程化兜底（适合长期项目）

17. CI 是最终裁判：无论 AI 和人怎么合作，合并门槛始终是 CI 绿灯（编译、测试、静态检查、安全扫描），不依赖任何人的口头确认。
18. 沙箱先跑：不确定的脚本、迁移、批量操作，先在副本数据/沙箱环境执行，验证后再上真实环境。

---

一句话概括

把 AI 当作一个能力极强但不知轻重的初级工程师——任务书（spec + 范围）给清楚，验收标准（测试 + CI）卡死，关键决策（架构、删改、依赖）留在人手里。

下面是 AGENTS.md 示例

# AGENTS.md

-  本文件是 AI 编码助手的项目宪法。每次会话开始时必须先完整阅读本文件。
-  核心原则：AI 负责快，人负责准；AI 的每次输出都必须能被验证。

## 1. 项目概况

- 项目名称：
- 项目简介：
- 技术栈（语言 / 框架 / 依赖管理）：
- 关键程度说明（如涉及资金/鉴权/数据迁移，见第 7 节关键路径清单）：

## 2. 任务边界（每次会话必须遵守）

1. **范围声明先行**：每次会话开头，人会明确声明本次修改范围。你只允许修改范围内的文件，不得自行扩大范围。
2. **单一任务原则**：一次会话只解决一个问题。复杂任务拆成多步，每步可验证、可回滚后再进行下一步。
3. **先复述、后动手**：开始编码前，先用 3-5 句话复述你理解的任务、范围与约束，经人确认后才允许写代码。
4. **不静默改无关代码**：禁止顺手重构、格式化、修复无关警告；diff 中不应出现与任务无关的改动。

## 3. 代码库规范

- 目录结构说明：
- 命名约定：
- 代码风格（lint / format 工具及配置）：
- 分支与提交规范（commit message 格式、分支命名）：

## 4. 验证要求

1. **测试先于结论**：声称"完成/修复"时，必须给出实际运行的命令和真实输出；无证据的结论视为未完成。
2. **黄金样本回归**：关键功能以 `tests/golden/` 下的样例为准做回归，而不仅仅依赖你自行编写的测试。
3. **双模型交叉评审**：重要改动完成后，输出 diff 供另一模型 review，并主动列出可能的逻辑错误与遗漏的边界条件。
4. **破坏清单**：删除文件、修改数据库结构、修改公开 API、修改配置类之前，先列出清单，经人逐条确认后执行。

## 5. Spec 与上下文

1. **Spec 先行**：接口、数据结构、状态机的变更，先更新 `docs/spec/` 下的对应文档，再改代码。以 spec 为准绳，不以对话记忆为准。
2. **上下文即证据**：引用项目事实时必须标注依据（文件路径 / 文档名）；信息不足时输出"无法确定，需要查看 X 文件"，禁止猜测接口行为或依赖版本。
3. **外部依赖变更**：新增、升级、删除任何依赖，必须先说明理由并获批准。

## 6. 增量与可回滚

1. **小步提交**：改动按逻辑拆分为多个小 commit，每个 commit 独立可编译、可通过测试。
2. **先探针、后实施**：大改动前先做只读侦察：列出影响文件、风险点、备选方案，经人确认方案后再实施。
3. **沙箱先跑**：不确定的脚本、迁移、批量操作，先在沙箱或副本数据上执行，验证后再上真实环境。

## 7. 关键路径（人工逐行审查，不得批量通过）

- 鉴权 / 权限校验：
- 资金 / 账务：
- 并发 / 事务：
- 数据迁移：
- 其他：

## 8. 合并门槛

- **CI 是最终裁判**：合并必须 CI 全绿（编译、测试、静态检查、安全扫描）。
- PR 描述必须包含：改了什么、为什么改、影响面、验证方式。

## 9. 禁止事项（硬性）

- 禁止修改范围外的文件
- 禁止静默重构 / 格式化无关代码
- 禁止新增依赖未获批准
- 禁止在未确认的情况下执行破坏性操作
- 禁止在信息不足时猜测而非提问

---

## 一句话定位

把 AI 当作能力极强但不知轻重的初级工程师——任务书（spec + 范围）给清楚，验收标准（测试 + CI）卡死，关键决策（架构、删改、依赖）留在人手里。