很多团队第一次把 AI 编程助手接入真实项目时，都会经历一个相似的过程：

一开始觉得它写代码很快，几分钟就能完成过去需要半小时的修改；但任务一复杂，问题就开始出现：

• 明明项目统一使用 pnpm，它却生成了 npm install；
• 只要求修改接口校验，却顺手重构了不相关模块；
• 代码可以运行，但没有补测试；
• 新增文件没有遵守目录约定；
• 修改了数据库结构，却没有生成迁移文件；
• 本地测试通过，提交后却被 CI 拒绝。

这些问题不一定是模型能力不足，更常见的原因是：项目中的隐性规则没有被写成 AI 可以稳定读取的显式上下文。

人类开发者加入团队后，会通过 Code Review、文档、口头沟通和历史代码逐渐理解规则；AI 编程助手每次接收任务时，却可能从一个全新的上下文开始。如果仓库里只有 README 和零散注释，它就只能根据通用经验猜测。

解决思路不是把提示词写得越来越长，而是为仓库建立一套可以复用、可以版本控制、可以自动验证的“项目指令层”。

---

一、AI 改错代码，通常不是因为不会写

先看一个常见任务：

为用户注册接口增加邮箱格式校验，并补充测试。

对于开发者来说，这句话背后可能包含很多默认约定：

1. 校验逻辑必须放在 DTO 层；
2. 统一使用项目已有的校验库；
3. 错误信息必须使用错误码，不直接写中文；
4. 单元测试放在 tests/unit；
5. 运行测试时使用 pnpm test:unit；
6. 不允许修改数据库模型；
7. 不允许为了“代码更整洁”重构其他模块。

如果这些约定没有出现在任务描述或仓库文档中，AI 只能自行判断。它可能完成了“邮箱校验”，但完成方式并不符合项目规范。

因此，AI 编程质量可以粗略理解为：

最终结果 = 模型能力 × 项目上下文质量 × 验证闭环

模型负责推理和执行，仓库指令负责约束边界，测试和检查脚本负责发现偏差。三者缺一不可。

---

二、仓库级指令文件到底解决什么问题

不同工具使用的指令文件名称不完全相同，例如：

工具或场景	常见仓库指令文件
Codex	AGENTS.md
Claude Code	CLAUDE.md
GitHub Copilot	.github/copilot-instructions.md
团队自建 Agent	自定义 Markdown、YAML 或系统提示词

文件名虽然不同，目标基本一致：让 AI 在执行任务之前，先理解仓库结构、技术栈、操作边界和验收标准。

一份有效的仓库级指令，至少应该回答下面几个问题：

• 这个项目使用什么技术栈？
• 代码应该放在哪里？
• 哪些目录不能修改？
• 安装、构建、测试和检查命令是什么？
• 新功能必须补哪些测试？
• 什么情况下必须先询问，而不能直接修改？
• 完成任务后应该如何汇报？

这些信息不应该只存在于某位核心开发者的经验中，而应该跟随代码一起进入版本控制。

---

三、不要复制三套规则，先建立一个“单一事实源”

如果团队同时使用多个 AI 编程工具，最容易犯的错误是分别维护三份完整规则：

AGENTS.md
CLAUDE.md
.github/copilot-instructions.md

刚开始内容一致，几个月后就会出现差异：

• 一份写着 Node.js 20，另一份仍是 Node.js 18；
• 一份要求运行 E2E 测试，另一份没有更新；
• 某个废弃目录只在其中一份被标记为禁止修改。

更稳妥的方式是建立一个公共规则文件，再让不同工具的入口文件保持简短。

推荐结构：

project/
├─ AGENTS.md
├─ CLAUDE.md
├─ .github/
│   └─ copilot-instructions.md
├─ docs/
│   ├─ ai-context.md
│   ├─ architecture.md
│   └─ testing.md
├─ scripts/
│   └─ verify.sh
└─ package.json

其中：

• docs/ai-context.md：统一维护项目规则；
• architecture.md：解释模块边界和依赖方向；
• testing.md：说明测试类型与执行条件；
• 各工具入口文件：告诉工具先读取哪些公共文档；
• verify.sh：把验收动作变成可执行脚本。

这样可以尽量避免多份文档长期漂移。

---

四、一份可直接改造的仓库指令模板

下面是一份偏通用的 docs/ai-context.md 示例。

# Project AI Context
1. Project overview
Runtime: Node.js 20
Package manager: pnpm
Framework: NestJS
Database: PostgreSQL
ORM: Prisma
Test framework: Vitest
2. Repository structure
src/modules: business modules
src/common: shared infrastructure
prisma: schema and migrations
tests/unit: unit tests
tests/integration: integration tests
3. Required commands
Install dependencies:
pnpm install
Run type checking:
pnpm typecheck
Run lint:
pnpm lint
Run unit tests:
pnpm test:unit
Run full verification:
./scripts/verify.sh
4. Change boundaries
Do not edit generated files.
Do not change database schema unless the task explicitly requires it.
Do not introduce new dependencies before checking existing utilities.
Do not refactor unrelated modules.
Do not remove tests to make the build pass.
5. Coding conventions
Reuse existing error codes.
Keep controllers thin.
Put business logic in services.
All public functions require explicit return types.
New behavior must include tests.
6. Completion requirements
Before finishing:
Review the diff.
Run the smallest relevant test set.
Run type checking.
Report changed files.
Report tests executed.
Disclose any unverified assumptions.

这份模板的重点不在于内容多，而在于规则可执行、可验证。

例如，“代码要优雅”很难验证；而“控制器只负责参数接收，业务逻辑放在 service”更具体。

“记得测试”也不够明确；“修改业务行为时必须增加单元测试，并执行 pnpm test:unit”更容易落实。

---

五、为不同工具保留轻量入口文件

1. AGENTS.md

# Repository Instructions
Before making changes, read:
docs/ai-context.md
docs/architecture.md
docs/testing.md
Follow the nearest nested AGENTS.md when working inside a subdirectory.
Do not modify unrelated files.
Before completing the task, run ./scripts/verify.sh or explain why it could not be run.

2. CLAUDE.md

# Project Instructions
Read docs/ai-context.md before editing code.
Use docs/architecture.md for module boundaries.
Use docs/testing.md to select the required tests.
Keep changes limited to the requested task.
Run ./scripts/verify.sh before reporting completion.

3. .github/copilot-instructions.md

Use `docs/ai-context.md` as the primary project rule set.
When suggesting or changing code:
follow the repository structure;
avoid unrelated refactoring;
reuse existing dependencies;
add tests for behavior changes;
validate with the commands documented in docs/testing.md.

入口文件不必重复所有细节。它们更像索引，负责把工具引导到公共规则。

---

六、规则应该分层，而不是全部堆在根目录

大型仓库往往包含前端、后端、基础设施和移动端代码。把所有规则塞进根目录文件，会带来两个问题：

1. 文件越来越长，真正重要的内容被淹没；
2. 某个子项目的规则可能错误影响其他目录。

可以采用分层结构：

project/
├─ AGENTS.md
├─ apps/
│   ├─ web/
│   │   └─ AGENTS.md
│   └─ api/
│       └─ AGENTS.md
└─ packages/
    └─ ui/
        └─ AGENTS.md

根目录只定义全局规则，例如安全要求、提交规范和公共验证流程。

子目录文件则描述局部约定：

# Web App Instructions
Framework: Next.js
Use server components by default.
Client components must include a clear reason.
Reuse components from packages/ui.
Run pnpm --filter web test.
Do not access the database directly from UI code.

这样，AI 进入 apps/web 工作时，可以获得更精准的上下文，而不需要读取与当前任务无关的大量后端规则。

---

七、把“完成标准”写成脚本，而不是一句提醒

仅靠文档无法保证 AI 一定执行正确。更可靠的方式，是把检查动作封装为统一命令。

示例 scripts/verify.sh：

#!/usr/bin/env bash
set -euo pipefail
echo "[1/4] Type checking"
pnpm typecheck
echo "[2/4] Lint"
pnpm lint
echo "[3/4] Unit tests"
pnpm test:unit
echo "[4/4] Build"
pnpm build
echo "Verification completed."

赋予执行权限：

chmod +x scripts/verify.sh

仓库指令中只需要明确要求：

完成任务前运行 ./scripts/verify.sh。
如果无法运行，必须说明失败步骤、错误信息和未验证风险。

这个做法有三个好处：

• 人和 AI 使用同一套验收流程；
• CI 可以复用相同命令；
• 当项目命令变化时，只需要维护脚本。

---

八、任务提示词仍然重要，但只描述“本次变化”

仓库级规则不能替代任务提示词。

仓库文件适合存放长期不变的内容：

• 技术栈；
• 目录结构；
• 测试命令；
• 代码风格；
• 禁止修改区域；
• 完成标准。

本次任务提示词则应该描述具体目标：

目标：
为 POST /users/register 增加邮箱格式校验。
范围：
只修改 users 模块和对应单元测试。
验收：
非法邮箱返回现有错误码 USER_EMAIL_INVALID；
合法邮箱行为不变；
不修改 Prisma Schema；
执行 users 模块单元测试；
输出修改文件和测试结果。

一个好的任务描述，应该让 AI 清楚知道“改什么、不要改什么、怎样算完成”。

---

九、仓库指令最常见的五个反模式

反模式 1：把文件写成几十页说明书

指令过长不代表效果更好。大量背景故事、历史记录和重复规则会降低可读性。

更好的做法是让入口文件保持简短，把架构、测试和发布规则拆到独立文档。

反模式 2：只写风格，不写命令

“保持代码整洁”“遵循最佳实践”几乎无法执行。

应该明确告诉 AI 使用哪个包管理器、运行哪些命令、测试放在哪里。

反模式 3：规则与代码不同步

项目已经从 Jest 迁移到 Vitest，文档仍要求运行 npm test，AI 就会按照错误信息执行。

建议把仓库指令纳入 Code Review 范围。修改技术栈、目录或 CI 时，同步更新对应文档。

反模式 4：允许顺手重构

AI 经常会为了让代码“更一致”修改不相关文件，导致 Diff 迅速扩大。

仓库规则应明确：

除非任务明确要求，否则不要重构无关模块。

反模式 5：只要求“测试通过”，不要求报告

AI 可能只运行了一个局部测试，却给出“所有测试通过”的模糊结论。

应该要求它报告：

• 实际执行的命令；
• 通过和失败情况；
• 未执行的测试；
• 未验证的假设。

---

十、如何判断这套规则是否真的有效

不要只看 AI 的回答是否更“像懂项目”，应该通过数据观察效果。

可以记录以下指标：

指标	观察方式
无关文件修改数量	对比每次任务的 Git Diff
首次 CI 通过率	统计 AI 提交首次进入 CI 的结果
漏测次数	统计行为变更但未补测试的情况
人工返工时间