AI智能体工程实践手册：从混乱到纪律的完整指南

普遍困境：AI编码工具的失控体验

使用AI编码智能体（如Claude Code、Cursor、GitHub Copilot等）的团队普遍面临相同的困境：智能体写代码很快，但生成的代码往往不遵循团队约定、破坏现有模式、引入lint错误，并产生不一致的提交历史。开发者最终花费与手写代码相当的时间来修正AI的错误。

这种"快速但混乱"的模式带来了几个深层问题：

• 质量不一致：一次会话遵循约定，下一次就无视规范。提交信息随机、类型注解缺失、lint错误漏过检查、架构违规需要数天才能理清。

• 没有机构记忆：每个AI会话从零开始。它不知道你的分支策略、测试约定、异常层次结构，也不记得上周你花了4小时追踪的bug。你不得不在每个会话中重复相同的纠正。

• CI打地鼠：推送、等待5分钟CI、发现lint错误、修复、再推送、再等5分钟、发现类型错误……这个循环摧毁心流并产生嘈杂的提交历史。

• 质量债务悄然累积：没有度量标准来约束，每个"就这一次"的例外都成为永久。类型忽略增长、lint抑制增长、复杂度增长——直到代码库变得难以维护。

• 调试知识流失：你花了2小时发现某个库的默认超时是10秒。下个月，某人（或某个智能体）遇到同样的问题。知识曾短暂存在于对话中，然后消失。

手册核心：让AI成为守纪律的贡献者

这份手册提供了一个完整的工程流程——从生产级应用中提炼——使AI智能体从混乱的贡献者转变为守纪律的协作者。它涵盖了从智能体指令配置、质量门禁防止回归，到调试知识如何随时间复利增长的所有内容。

13个工程领域全覆盖

手册以1400多行详细指南，覆盖13个关键工程领域，面向需要建立新项目的初级工程师：

1. 哲学与原则

质量棘轮机制、本地CI等于远程CI、复利学习、诚实的对立面——建立AI辅助开发的底层思维框架。

2. Agent.md作为项目宪法

单个文件让每个AI会话都变得高效。这是手册最核心的创新之一。

3. 智能体工具配置

Serena（MCP服务器）、智能体设置、记忆系统的配置指南。

4. 技能系统

智能体按需激活的可复用工作流（提交、审查、头脑风暴）。

5. 分支与工作树工作流

人类和智能体同时工作的并行安全隔离方案。

6. 代码质量门禁

两层体系：本地CI（推送前）和远程CI（安全网）——相同的检查，相同的真相来源。

7. 代码健康度量

可维护性指数、复杂度、文件大小、重复度、质量棘轮。

8. CI/CD流水线

检查的单一真相来源、开发优先晋升、零重建部署。

9. 架构模式

异常层次结构、工作单元、仓库模式、任务队列协议。

10. 测试策略

Pytest配置、fixtures、异步模式、什么不该测试。

11. 文档基础设施

架构文档、经验教训、复利学习循环。

12. 基础设施与DevOps

开发环境设置、扩展/收缩迁移、密钥管理、部署。

13. 采用路线图

从第1天到第2个月以上的分阶段推广计划。

核心解决方案详解

Agent.md：项目宪法

项目根目录下的一个markdown文件，AI编码智能体在每个会话开始时读取。它定义规则、约定和架构决策。没有它，每个会话从零开始；有了它，智能体从第一条消息就知道你的分支策略、测试约定、异常层次结构和文件大小限制。

对于Claude Code，这个文件命名为CLAUDE.md。对于其他智能体，可以适配为.cursorrules、.github/copilot-instructions.md等。内容相同——手册使用通用名称Agent.md。

质量棘轮：度量只进不退

这是手册最具创新性的概念之一。度量标准只能改善，绝不能倒退。每个PR都会与其合并基准进行比较：

• 添加了一个# type: ignore？在其他地方移除一个。
• 引入了复杂度违规？简化它。
• 新的公共函数没有类型注解？补上它们。

这由quality_delta.py强制执行，它在PR上运行，如果任何度量倒退就会失败。

本地CI等于远程CI

单个ci-checks.json文件定义所有检查。本地运行器（ci_check_local.py）和远程CI工作流都从这个文件读取。提交需要多花30-60秒，但替代方案——推送-等待-失败-修复-推送-等待-失败-修复——浪费更多时间并产生嘈杂的历史。

多角色代码审查

五个专业审查者并行调度，每个专注于自己最擅长的领域：

• 正确性：逻辑错误、边界情况、状态bug
• 测试：覆盖缺口、弱断言
• 项目标准：约定合规性
• 安全（条件性）：注入、认证、数据暴露
• 对抗性（条件性）：失败场景、级联故障

每个审查者都有一个角色文档，定义要寻找什么、忽略什么、如何校准置信度。

复利学习三步循环

让代码库随时间变得更智能的三步循环：

1. 咨询：开始工作前搜索docs/lessons-learned/
2. 捕获：解决非平凡bug后写一条经验
3. 晋升：当一条经验反复出现时，将其提升为Agent.md中的规则

立即可用的快速启动方案

手册提供了最小努力获得即时价值的路径：

基础设置（5分钟）

1. 复制Agent.md到项目根目录，编辑以匹配你的约定
2. 设置本地CI：复制检查定义和运行器脚本
3. 在每次提交前运行：

   python scripts/ci_check_local.py --fix
   

   脚本自动修复格式/lint问题，并验证其他所有内容（类型、测试、代码健康、迁移）。

进阶采用（数小时到数天）

• 添加scripts/check_code_health.py到ci-checks.json
• 创建.type-ignore-threshold记录当前数量
• 在CI工作流中镜像ci-checks.json
• 复制skills/commit/和skills/code-review/到项目
• 在第一次非平凡调试会话后创建docs/lessons-learned/

完整采用（数周到数月）

• 调整skills/code-review/personas/project-standards.md以匹配你的约定
• 添加quality_delta.py进行PR回归检查
• 设置Serena MCP进行语义代码导航
• 添加头脑风暴技能用于设计工作流

技术栈适配性

手册基于Python/FastAPI + React/TypeScript技术栈开发，但原则和大部分工具都是可适配的：

组件	本手册使用	替代方案
Python linter/formatter	ruff	black + flake8, pylint
类型检查器	mypy	pyright, pytype
代码度量	radon	wily, complexipy
重复检测	jscpd	CPD, Simian
死代码检测	vulture	pylint unused-import
依赖检查	deptry	pip-extra-reqs
任务队列	SAQ	Celery, Dramatiq, Arq
迁移工具	Alembic	Django migrations, Flyway
代码导航	Serena (MCP)	—
智能体	Claude Code	Cursor, Copilot, Aider

项目意义

这份手册的价值在于它提供了一个经过生产验证的完整框架，而非零散的提示词集合。它将AI辅助开发从"试试运气"转变为可工程化管理的流程。

对于正在或计划采用AI编码工具的团队，这份手册提供了：

1. 即用的起点：不必从零摸索，可以基于经过验证的实践开始
2. 渐进式采用路径：从5分钟的基础设置到数月的完整采用，团队可以根据自身节奏选择
3. 质量保障机制：通过质量棘轮和双重CI体系，确保AI贡献不会降低代码库质量
4. 知识沉淀方法：通过复利学习循环，将调试经验转化为可复用的规则

在AI编码工具快速迭代的今天，这份手册代表了一种务实的方法论——不是盲目追逐最新工具，而是建立让任何AI工具都能高效协作的工程纪律。