上下文工程：把AI编程从玄学变成工程实践

痛点引入

你有没有经历过这样的深夜：对着Claude Code反复改prompt，加‘请用Java 17’、删‘不要用Lombok’、补‘字段命名遵循snake_case’，最后AI还是生成了一个带@Data但没写toString()的DTO？不是模型不行，是你没把它当工程师管——你只给了需求，没给工程规范，没给验收标准，更没给失败回滚路径。

这不是个别现象。我司去年上线AI SQL生成模块，90%的线上问题不是大模型胡说八道，而是它根本不知道我们MySQL用的是utf8mb4，不知道user_profile.status字段合法值是'ENABLED'而非'active'，甚至不知道created_at必须用CURRENT_TIMESTAMP而非NOW()。这些不是LLM缺陷，是上下文缺失。

解决方案

context-engineering-intro 就是为此而生：它不训练模型，不封装API，不做任何后端服务——它只做一件事：把人和AI的协作过程，变成可版本化、可Review、可Pipeline化的文本工程。

它不是库，是模板；不是SDK，是协议；不是CLI工具，是.gitignore级别的基础设施。整个项目结构干净得像一张白纸：

├── .claude/
│   └── commands/
│       ├── generate-prp.md    ← AI世界的Makefile
│       └── execute-prp.md   ← CI流水线脚本
├── CLAUDE.md              ← 全局工程规范（如：'所有Service必须继承BaseService'）
├── INITIAL.md             ← 需求PRD（Feature Spec）
├── PRPs/                  ← 生成的设计文档（含Success Criteria + Validation Gates）
├── examples/              ← 单元测试级样板（真实代码片段，非伪代码）
└── DOCUMENTATION/         ← 外部契约链接（OpenAPI、DB Schema、MCP资源）

这哪是AI项目？这是用Markdown写的微服务治理框架。

核心代码解析

先看最灵魂的一行命令：

## 在 Claude Code 中执行
/generate-prp INITIAL.md

别被/开头骗了——这不是普通指令，是上下文编排触发器。它背后执行的是：

1. 加载 .claude/commands/generate-prp.md —— 这个文件本质是结构化Prompt模板，声明了输入变量（{{INITIAL}}）、上下文注入规则（自动拼接CLAUDE.md+examples/+DOCUMENTATION/）、输出约束（必须含## SUCCESS CRITERIA和## VALIDATION GATES）；
2. 解析 INITIAL.md 中的 ## FEATURE、## EXAMPLES 等区块，提取语义标签；
3. 扫描 examples/ 目录，按## EXAMPLES中声明的文件名加载对应样板，作为行为锚点（behavior anchor）；
4. 最终生成一份带完整验证门禁的PRP文档，例如：

## SUCCESS CRITERIA
- 新增UserService.createProfile()方法
- 返回值必须是ResponseEntity<ProfileDTO>
- 必须调用validateEmail()前置校验

## VALIDATION GATES
1. [ ] 检查UserService.java是否新增createProfile方法签名
2. [ ] 检查ProfileDTO.java是否包含email、fullName字段且类型正确
3. [ ] 运行mvn test -Dtest=UserServiceTest#testCreateProfile

再看执行阶段：

/execute-prp PRPs/user-profile-v2.md

这步才是真正进入「工程师模式」：

• Plan：AI用TodoWrite格式拆解任务（[ ] 修改UserService.java, [ ] 新增ProfileDTO.java, [ ] 补充单元测试）；
• Execute：逐文件修改，且每个修改都附带变更理由（// 因PRP要求返回ResponseEntity<ProfileDTO>，故重构返回类型）；
• Validate：自动运行预设检查项（grep -r "ResponseEntity<ProfileDTO>" src/main/java/, mvn compile）；
• Iterate：若某项失败（如编译报错），AI不抛异常，而是读取错误日志，定位到ProfileDTO缺少@Data注解，自动补上并重试。

整个流程完全复刻Jenkins Pipeline的stages { stage('Build') { steps { sh 'mvn compile' } } }逻辑，只是执行引擎换成了Claude Code会话。

实战演示：为Spring Boot项目添加JWT认证模块

假设你要在现有项目中集成JWT：

1. 编写 INITIAL.md：

## FEATURE:
新增JWT认证拦截器，对/api/**路径进行token校验，校验失败返回401

## EXAMPLES:
examples/jwt-filter.java  ← 提供已验证的Filter样板
examples/jwt-config.yml  ← 提供application.yml配置片段

## DOCUMENTATION:
https://docs.spring.io/spring-security/reference/servlet/authentication/jwt.html

## OTHER CONSIDERATIONS:
- token需从Authorization Header的Bearer前缀提取
- 必须使用RSA256算法，公钥由配置中心下发

2. 执行 /generate-prp INITIAL.md → 自动生成 PRPs/jwt-auth-v1.md，含明确的Success Criteria和Validation Gates；

3. 执行 /execute-prp PRPs/jwt-auth-v1.md → AI自动：

   • 创建 JwtAuthFilter.java（继承OncePerRequestFilter）
   • 修改 application.yml 增加 jwt.public-key-url 配置项
   • 在 SecurityConfig.java 中注册该Filter
   • 补充 JwtAuthFilterTest.java，覆盖token缺失、过期、签名错误三种case

全程无需你写一行Java——但你写了全部工程契约。

踩坑指南

• Claude Code生态绑定：目前仅支持Claude Code的Slash Command，Cursor/GitHub Copilot无法直接复用.claude/commands/。变通方案：把generate-prp.md内容复制进Copilot的Custom Command，但会丢失自动上下文注入能力；
• examples质量即AI质量：如果你的examples/jwt-filter.java只写了空壳类，AI就真给你空壳。必须提供真实可运行的样板，包括import、注释、边界处理（如try-catch）；
• CLAUDE.md不是风格指南，是契约：写'所有Controller返回值必须是ResponseEntity<T>'可以，写'代码要优雅'不行——后者无法自动化验证。

个人评价

作为写过12年Java的老兵，我敢说：这是近两年看到的最硬核的AI工程化实践。它没有试图“让AI更聪明”，而是坚定地“让人更严谨”。当你把CLAUDE.md改成团队《Spring Boot开发规范V4.1》，把examples/塞满5种Service模板、3种DTO生成策略、2种异常处理范式时，你就在构建属于你们团队的AI协作者DNA。

它不承诺“零代码”，但承诺“零歧义”；不降低技术门槛，但抬高协作水位线。就像Dockerfile之于运维，context-engineering-intro 正在定义AI时代的Dockerfile——用纯文本，把混沌的人机协作，编译成可交付、可审计、可传承的工程资产。

最后提醒一句：别急着fork。先打开你的CLAUDE.md，把第一条规则写成：'所有PRP必须声明SUCCESS CRITERIA，且每条Criterion必须可自动化验证'。这才是真正的起点。