03d - 上下文工程实战清单

本文是《AI Agent 实战手册》第 3 章第 4 节。 上一节：上下文窗口管理策略 | 下一节：Metaprompt 概念与动机

概述

前三节讲了方法论、规则文件和窗口管理。本节把这些知识浓缩为一份可执行的实战清单——当你启动一个新项目或接手一个现有项目时，按这份清单逐项落实，就能快速建立高质量的上下文工程体系。同时提供 3 个前后对比案例，展示上下文工程带来的实际改善。

1. 新项目上下文工程清单

优先级 P0：必须在第一天完成

这些是上下文工程的基础，缺少任何一项都会显著降低 AI 辅助开发的效果。

优先级 P1：第一周内完成

这些项目能显著提升 AI 辅助开发的质量和一致性。

优先级 P2：持续迭代

这些是长期优化项，随着项目发展逐步完善。

2. 现有项目改造清单

如果你接手一个没有上下文工程的现有项目，按以下顺序改造：

操作步骤

步骤 1：快速评估（30 分钟）

请分析当前项目，回答以下问题：
1. 项目使用什么技术栈？列出语言、框架、主要依赖及版本
2. 项目目录结构是什么？列出 src/ 下的主要目录及用途
3. 有哪些常用开发命令？（构建、测试、lint、格式化）
4. 代码中有哪些明显的编码规范？（命名风格、错误处理模式、导入风格）
5. 有哪些潜在的"禁止事项"？（从代码中推断）

步骤 2：生成规则文件（15 分钟）

用步骤 1 的结果，让 AI 生成初始规则文件：

基于以上分析，为我生成一份 [CLAUDE.md / .cursorrules / Kiro Steering]。
要求：
- 简洁明确，每条规则一行
- 包含项目概述、技术栈、目录结构、常用命令、编码规范、禁止事项
- 总长度控制在 500 行以内

步骤 3：验证和调整（持续）

使用 AI 助手完成几个实际任务，观察行为：

• AI 是否遵循了规则文件中的规范？
• AI 是否犯了规则文件没有覆盖的错误？
• 规则文件中是否有 AI 误解的内容？

根据观察结果迭代更新规则文件。

3. 前后对比案例

案例 1：React 电商项目——从混乱到一致

背景

一个 3 人团队的 React 电商项目，使用 Cursor 辅助开发。AI 生成的代码风格不一致，每次都需要大量手动修正。

❌ 改造前（无上下文工程）

问题表现：

• AI 有时用 default export，有时用 named export
• 状态管理混用 useState、useReducer、Redux、Zustand
• API 调用有的用 fetch，有的用 axios，有的用 React Query
• 样式有的用 inline style，有的用 CSS Modules，有的用 Tailwind
• 错误处理不一致——有的用 try/catch，有的用 .catch()，有的完全没有

开发者体验：

• 每次 AI 生成代码后需要 15-30 分钟手动修正风格
• 代码审查时 60% 的评论是关于风格不一致
• 新功能开发时间：AI 生成 30 分钟 + 手动修正 45 分钟 = 75 分钟

✅ 改造后（实施上下文工程）

做了什么：

1. 创建 .cursorrules（15 分钟）：

## 导出规范
- 所有组件使用 named export，禁止 default export
 
## 状态管理
- 全局状态：Zustand（stores/ 目录）
- 服务端状态：React Query（hooks/queries/ 目录）
- 局部状态：useState（仅组件内部）
- 禁止使用 Redux 和 useReducer
 
## API 调用
- 所有 API 调用通过 React Query 封装
- API 函数定义在 api/ 目录
- 使用 axios 实例（lib/axios.ts），禁止直接用 fetch
 
## 样式
- 使用 Tailwind CSS，禁止 inline style 和 CSS Modules
- 复杂组件使用 clsx 合并类名
 
## 错误处理
- API 错误使用 React Query 的 onError 回调
- 表单验证使用 Zod + react-hook-form
- 全局错误边界在 app/error.tsx

2. 配置 Kiro Steering 条件规则（10 分钟）：
   • api-patterns.md：API 目录文件被读取时自动加载
   • testing-guide.md：测试文件被读取时自动加载

改善结果：

• AI 生成的代码 90%+ 符合项目规范，手动修正时间从 45 分钟降到 5 分钟
• 代码审查中风格相关评论从 60% 降到 5%
• 新功能开发时间：AI 生成 30 分钟 + 手动修正 5 分钟 = 35 分钟
• 效率提升：53%

案例 2：Rust 后端服务——从”猜测”到”精准”

背景

一个 Rust 微服务项目，使用 Claude Code 辅助开发。项目有特定的错误处理和日志规范，但 AI 总是生成不符合规范的代码。

❌ 改造前

问题表现：

• AI 使用 unwrap() 和 expect() 而不是 ? 操作符
• 错误类型使用 anyhow::Error 而不是项目自定义的 AppError
• 日志使用 println! 而不是 tracing crate
• 异步代码混用 tokio 和 async-std
• 测试不使用项目的 test helper 函数

典型 AI 输出：

// AI 生成的代码——不符合项目规范
fn process_file(path: &str) -> Result<String, Box<dyn std::error::Error>> {
    let content = std::fs::read_to_string(path).unwrap();  // ❌ unwrap
    println!("Processing: {}", path);                        // ❌ println
    Ok(content)
}

✅ 改造后

做了什么：

1. 创建 CLAUDE.md（20 分钟）：

# CLAUDE.md
 
## 错误处理
- 公共 API：使用 thiserror 定义的 AppError 枚举（src/error.rs）
- 内部实现：使用 ? 操作符传播错误
- 禁止：unwrap()、expect()、Box<dyn Error>、anyhow（已迁移完毕）
 
## 日志
- 使用 tracing crate：info!(), warn!(), error!()
- 禁止：println!(), eprintln!(), dbg!()
- 结构化日志：tracing::info!(file = %path, "Processing file");
 
## 异步
- 运行时：tokio（禁止 async-std）
- 所有 I/O 操作使用 tokio::fs 而非 std::fs
 
## 测试
- 使用 tests/helpers.rs 中的 setup_test_env() 初始化测试环境
- 异步测试使用 #[tokio::test]
- 属性测试使用 proptest crate

2. 在 src/ 子目录创建 CLAUDE.md（5 分钟）：

# src/CLAUDE.md
## 模块间依赖
- sync_engine 依赖 diff + transfer + error
- 新模块必须在 lib.rs 中注册
- 公共类型定义在 types.rs

改善后的 AI 输出：

// AI 生成的代码——完全符合项目规范
fn process_file(path: &str) -> Result<String, AppError> {
    let content = tokio::fs::read_to_string(path)
        .await
        .map_err(|e| AppError::FileRead { path: path.into(), source: e })?;
    tracing::info!(file = %path, "Processing file");
    Ok(content)
}

改善结果：

• 错误处理规范符合率从 20% 提升到 95%
• 日志规范符合率从 10% 提升到 98%
• 代码审查通过率从 40% 提升到 85%
• 每次代码生成节省约 10 分钟的手动修正时间

案例 3：全栈 SaaS——从”每次重复”到”自动化上下文”

背景

一个独立开发者的 SaaS 项目（Next.js + Supabase），使用 Kiro 辅助开发。每次开始新功能时都要花 10 分钟向 AI 解释项目背景。

❌ 改造前

问题表现：

• 每次新对话都要重复：“这是一个 Next.js 项目，用 Supabase 做后端，用 Tailwind 做样式…”
• AI 不知道项目的认证方案，每次都建议不同的方案
• 数据库操作有时用 Supabase client，有时用 Prisma（项目只用 Supabase）
• 部署配置每次都要重新说明

开发者每天的时间浪费：

• 重复解释项目背景：3-4 次 × 10 分钟 = 30-40 分钟/天

✅ 改造后

做了什么：

1. 创建 Kiro Steering 文件集（30 分钟）：

.kiro/steering/
├── project-overview.md          ← 始终包含
├── supabase-patterns.md         ← 条件包含：匹配 src/lib/supabase/**
├── api-routes.md                ← 条件包含：匹配 src/app/api/**
├── ui-components.md             ← 条件包含：匹配 src/components/**
└── deployment.md                ← 手动激活

2. 配置 MCP 连接（10 分钟）：

   • 连接 Supabase MCP Server → AI 能直接查询数据库 schema
   • 连接 Vercel MCP Server → AI 能查看部署状态

3. 创建 Spec 模板（15 分钟）：

   • 新功能开发使用 Kiro Spec 工作流
   • 需求 → 设计 → 任务拆分 → 逐步实现

改善结果：

• 重复解释时间从 30-40 分钟/天降到 0（规则文件自动加载）
• AI 始终使用正确的技术栈（Supabase，不再建议 Prisma）
• 条件包含确保 API 开发时自动加载 API 规范，UI 开发时自动加载组件规范
• 新功能开发流程标准化，质量更稳定
• 每天节省 30-40 分钟，每月节省约 10-13 小时

4. 上下文工程成熟度模型

评估你的项目处于哪个阶段，制定改进计划：

提示词模板：上下文工程快速启动

模板 1：项目分析

请分析当前项目并生成上下文工程报告：

1. 技术栈识别：列出所有语言、框架、主要依赖及版本
2. 项目结构分析：列出主要目录及用途
3. 编码规范推断：从现有代码中推断至少 8 条编码规范
4. 潜在禁止事项：从代码模式中推断至少 5 条禁止事项
5. 常用命令：从 package.json / Cargo.toml / Makefile 中提取
6. 上下文工程建议：基于项目规模和复杂度，推荐优先实施的上下文工程措施

模板 2：规则文件审查

请审查当前项目的规则文件（[CLAUDE.md / .cursorrules / Steering]），检查：

1. 完整性：是否覆盖了技术栈、项目结构、编码规范、常用命令、禁止事项？
2. 准确性：规则是否与实际代码一致？有没有过时的内容？
3. 一致性：规则之间是否有矛盾？
4. 简洁性：是否有冗余或过于啰嗦的规则？
5. 缺失项：基于代码分析，还有哪些重要规范没有被记录？

请给出具体的改进建议。

模板 3：上下文预算规划

我要完成以下任务：[任务描述]

请帮我规划上下文：
1. 必需文件：完成此任务必须读取的文件列表
2. 参考文件：有助于提高质量但非必需的文件
3. 可省略：与此任务无关的文件
4. 预估 token：每个文件的大约 token 数
5. 总预算：是否在 [模型窗口大小] 以内？如果超出，建议如何压缩？

避坑指南

❌ 常见错误

1. 一次性追求完美

   • 问题：花一整天写规则文件，结果很多规则在实际使用中不适用
   • 正确做法：从最小可用版本开始（P0 清单），在实际使用中迭代

2. 只建不维护

   • 问题：规则文件创建后再也没更新，半年后已经与项目脱节
   • 正确做法：将规则文件审查纳入每月例行工作，或在重大技术决策后立即更新

3. 团队成员不知道规则文件的存在

   • 问题：只有创建者使用规则文件，其他人继续”裸 prompt”
   • 正确做法：在团队 onboarding 文档中说明规则文件的位置和用途，纳入代码审查流程

4. 照搬别人的规则文件

   • 问题：从 cursor.directory 复制一份规则文件，但与自己项目的实际情况不匹配
   • 正确做法：社区模板作为起点，根据自己项目的实际情况定制

5. 忽略上下文工程的 ROI

   • 问题：觉得”花时间写规则文件不如直接写代码”
   • 正确做法：记录改造前后的效率数据（如案例所示），用数据证明投入产出比

✅ 最佳实践

1. 从 P0 清单开始，30 分钟内完成基础设置
2. 每次 AI 犯错时，思考”这个错误能通过规则文件避免吗？”
3. 将规则文件视为”活文档”，与代码一起版本控制和审查
4. 团队项目中，规则文件的变更应该经过代码审查

相关资源与延伸阅读

实战模板

• Awesome CLAUDE.md — GitHub  — 社区收集的 CLAUDE.md 模板和工作流，可直接参考
• Awesome CursorRules — GitHub  — 按技术栈分类的 .cursorrules 模板集合

检查与审计工具

• Repomix  — 将代码仓库打包为 AI 友好格式，方便审计上下文内容
• Langfuse  — 开源 LLM 可观测性平台，追踪上下文使用效率和成本

学习资源

• Context Engineering for AI Coding 101 — Packmind  — 上下文工程入门教程，包含实战清单
• Softcery Agentic Coding Best Practices  — 上下文文件和工作流的实战指南
• AI-Ready Codebase Guide — LLMX  — 让代码库对 AI Agent 友好的完整指南

社区

• r/ChatGPTCoding  — AI 编码社区，经常有上下文工程的实战经验分享
• Book of Kiro  — Kiro 社区知识库，包含上下文管理的最佳实践

参考来源

• Context Engineering Best Practices — Kubiya （2025-10）
• Context Engineering for AI Coding Agents — Pixelmojo （2026-02）
• Context Engineering AI Coding — Packmind （2025-12）
• AI Context Revolution: Essential Guide for 2026 — Vynta （2025-07）
• Context Engineering with OpenAI — Fractal AI （2026-02）

📖 返回 总览与导航 | 上一节：上下文窗口管理策略 | 下一节：Metaprompt 概念与动机