wehub-resource-sync
303 lines
9.1 KiB
Markdown
303 lines
9.1 KiB
Markdown
<!-- 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)
|