/README.md

<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/coleam00/context-engineering-intro) · [上游 README](https://github.com/coleam00/context-engineering-intro/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

# Context Engineering 模板

这是一份用于入门 Context Engineering（上下文工程）的综合模板——这门学科致力于为大模型编程助手构建上下文，使其掌握端到端完成任务所需的信息。

> **Context Engineering 比 prompt engineering（提示工程）好 10 倍，比 vibe coding（凭感觉写代码）好 100 倍。**

## 🚀 快速开始

```bash
# 1. Clone this template
git clone https://github.com/coleam00/Context-Engineering-Intro.git
cd Context-Engineering-Intro

# 2. Set up your project rules (optional - template provided)
# Edit CLAUDE.md to add your project-specific guidelines

# 3. Add examples (highly recommended)
# Place relevant code examples in the examples/ folder

# 4. Create your initial feature request
# Edit INITIAL.md with your feature requirements

# 5. Generate a comprehensive PRP (Product Requirements Prompt)
# In Claude Code, run:
/generate-prp INITIAL.md

# 6. Execute the PRP to implement your feature
# In Claude Code, run:
/execute-prp PRPs/your-feature-name.md
```

## 📚 目录

- [什么是 Context Engineering？](#what-is-context-engineering)
- [模板结构](#template-structure)
- [分步指南](#step-by-step-guide)
- [编写高效的 INITIAL.md 文件](#writing-effective-initialmd-files)
- [PRP 工作流](#the-prp-workflow)
- [有效使用示例](#using-examples-effectively)
- [最佳实践](#best-practices)

## 什么是 Context Engineering？

Context Engineering 代表了相对传统 prompt engineering 的范式转变：

### Prompt Engineering 与 Context Engineering 对比

**Prompt Engineering：**
- 侧重于巧妙的措辞与具体表述
- 仅限于你如何描述一项任务
- 就像给别人一张便利贴

**Context Engineering：**
- 一套用于提供全面上下文的完整系统
- 包含文档、示例、规则、模式和验证
- 就像撰写一份细节齐全的完整剧本

### 为什么 Context Engineering 很重要

1. **减少 AI 失败**：大多数 agent 失败并非模型能力不足，而是上下文不足
2. **确保一致性**：AI 会遵循你的项目模式与约定
3. **支持复杂功能**：在充足上下文下，AI 可以处理多步骤实现
4. **自我纠正**：验证循环让 AI 能够自行修复错误

## 模板结构

```
context-engineering-intro/
├── .claude/
│   ├── commands/
│   │   ├── generate-prp.md    # Generates comprehensive PRPs
│   │   └── execute-prp.md     # Executes PRPs to implement features
│   └── settings.local.json    # Claude Code permissions
├── PRPs/
│   ├── templates/
│   │   └── prp_base.md       # Base template for PRPs
│   └── EXAMPLE_multi_agent_prp.md  # Example of a complete PRP
├── examples/                  # Your code examples (critical!)
├── CLAUDE.md                 # Global rules for AI assistant
├── INITIAL.md               # Template for feature requests
├── INITIAL_EXAMPLE.md       # Example feature request
└── README.md                # This file
```

本模板暂不聚焦将 RAG 与工具纳入 context engineering，因为这方面我还有更多内容即将推出。;)

## 分步指南

### 1. 设置全局规则（CLAUDE.md）

`CLAUDE.md` 文件包含 AI 助手在每次对话中都会遵循的项目级规则。模板包括：

- **项目感知**：阅读规划文档、检查任务
- **代码结构**：文件大小限制、模块组织
- **测试要求**：单元测试模式、覆盖率期望
- **风格约定**：语言偏好、格式化规则
- **文档标准**：Docstring 格式、注释实践

**你可以直接使用提供的模板，也可以按项目自行定制。**

### 2. 创建初始功能需求

编辑 `INITIAL.md`，描述你想构建的内容：

```markdown
## FEATURE:
[Describe what you want to build - be specific about functionality and requirements]

## EXAMPLES:
[List any example files in the examples/ folder and explain how they should be used]

## DOCUMENTATION:
[Include links to relevant documentation, APIs, or MCP server resources]

## OTHER CONSIDERATIONS:
[Mention any gotchas, specific requirements, or things AI assistants commonly miss]
```

**完整示例见 `INITIAL_EXAMPLE.md`。**

### 3. 生成 PRP

PRP（Product Requirements Prompts，产品需求提示）是包含以下内容的综合实现蓝图：

- 完整上下文与文档
- 带验证的实现步骤
- 错误处理模式
- 测试要求

它们与 PRD（Product Requirements Documents，产品需求文档）类似，但更为专门地用于指导 AI 编程助手。

在 Claude Code 中运行：
```bash
/generate-prp INITIAL.md
```

**注意：** 这些斜杠命令是在 `.claude/commands/` 中定义的自定义命令。你可以查看其实现：
- `.claude/commands/generate-prp.md` —— 了解其如何调研并创建 PRP
- `.claude/commands/execute-prp.md` —— 了解其如何根据 PRP 实现功能

这些命令中的 `$ARGUMENTS` 变量会接收你在命令名之后传入的参数（例如 `INITIAL.md` 或 `PRPs/your-feature.md`）。

该命令将：
1. 读取你的功能需求
2. 调研代码库中的模式
3. 搜索相关文档
4. 在 `PRPs/your-feature-name.md` 中创建完整的 PRP

### 4. 执行 PRP

生成后，执行 PRP 以实现你的功能：

```bash
/execute-prp PRPs/your-feature-name.md
```

AI 编程助手将：
1. 读取 PRP 中的全部上下文
2. 制定详细的实现计划
3. 逐步执行并验证
4. 运行测试并修复问题
5. 确保满足所有成功标准

## 编写高效的 INITIAL.md 文件

### 关键章节说明

**FEATURE**：具体且全面
- ❌ "构建一个网页爬虫"
- ✅ "构建一个使用 BeautifulSoup 的异步网页爬虫，从电商网站提取产品数据，处理速率限制，并将结果存入 PostgreSQL"

**EXAMPLES**：善用 examples/ 文件夹
- 将相关代码模式放入 `examples/`
- 引用应遵循的具体文件与模式
- 说明应模仿哪些方面

**DOCUMENTATION**：包含所有相关资源
- API 文档 URL
- 库使用指南
- MCP 服务器文档
- 数据库 schema

**OTHER CONSIDERATIONS**：记录重要细节
- 身份认证要求
- 速率限制或配额
- 常见陷阱
- 性能要求

## PRP 工作流

### /generate-prp 如何工作

该命令遵循以下流程：

1. **调研阶段**
   - 分析代码库中的模式
   - 搜索类似实现
   - 识别应遵循的约定

2. **文档收集**
   - 获取相关 API 文档
   - 纳入库文档
   - 补充陷阱与注意事项

3. **蓝图创建**
   - 创建分步实现计划
   - 包含验证关卡
   - 添加测试要求

4. **质量检查**
   - 评估置信度（1-10）
   - 确保包含全部上下文

### /execute-prp 如何工作

1. **加载上下文**：读取完整 PRP
2. **规划**：使用 TodoWrite 创建详细任务列表
3. **执行**：实现各个组件
4. **验证**：运行测试与 lint
5. **迭代**：修复发现的问题
6. **完成**：确保满足所有要求

生成内容的完整示例见 `PRPs/EXAMPLE_multi_agent_prp.md`。

## 有效使用示例

`examples/` 文件夹对成功**至关重要**。当 AI 编程助手能看到可遵循的模式时，表现会好得多。

### 示例中应包含什么

1. **代码结构模式**
   - 模块组织方式
   - import 约定
   - 类/函数模式

2. **测试模式**
   - 测试文件结构
   - Mock 方法
   - 断言风格

3. **集成模式**
   - API 客户端实现
   - 数据库连接
   - 身份认证流程

4. **CLI 模式**
   - 参数解析
   - 输出格式化
   - 错误处理

### 示例结构

```
examples/
├── README.md           # Explains what each example demonstrates
├── cli.py             # CLI implementation pattern
├── agent/             # Agent architecture patterns
│   ├── agent.py      # Agent creation pattern
│   ├── tools.py      # Tool implementation pattern
│   └── providers.py  # Multi-provider pattern
└── tests/            # Testing patterns
    ├── test_agent.py # Unit test patterns
    └── conftest.py   # Pytest configuration
```

## 最佳实践

### 1. 在 INITIAL.md 中明确说明
- 不要假设 AI 了解你的偏好
- 包含具体的要求和约束
- 大量引用示例

### 2. 提供全面的示例
- 示例越多 = 实现越好
- 同时展示该做什么和不该做什么
- 包含错误处理模式

### 3. 使用验证关卡
- PRP 包含必须通过测试命令
- AI 会迭代直到所有验证通过
- 这确保第一次就能得到可运行的代码

### 4. 利用文档
- 包含官方 API 文档
- 添加 MCP 服务器资源
- 引用具体的文档章节

### 5. 自定义 CLAUDE.md
- 添加你的约定
- 包含项目特定规则
- 定义编码标准

## 资源

- [Claude Code 文档](https://docs.anthropic.com/en/docs/claude-code)
- [上下文工程（Context Engineering）最佳实践](https://www.philschmid.de/context-engineering)