docs: make Chinese README the default

2026-07-13 10:45:37 +00:00
parent f07589a5df
commit 6c20dae196
1 changed files with 162 additions and 156 deletions
@@ -1,10 +1,16 @@
-# Context Engineering Template
+<!-- 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 文件为准。

-A comprehensive template for getting started with Context Engineering - the discipline of engineering context for AI coding assistants so they have the information necessary to get the job done end to end.
+# Context Engineering 模板

-> **Context Engineering is 10x better than prompt engineering and 100x better than vibe coding.**
+这是一份用于入门 Context Engineering（上下文工程）的综合模板——这门学科致力于为大模型编程助手构建上下文，使其掌握端到端完成任务所需的信息。

-## 🚀 Quick Start
+> **Context Engineering 比 prompt engineering（提示工程）好 10 倍，比 vibe coding（凭感觉写代码）好 100 倍。**
+
+## 🚀 快速开始

 ```bash
 # 1. Clone this template
@@ -29,40 +35,40 @@ cd Context-Engineering-Intro
 /execute-prp PRPs/your-feature-name.md
 ```

-## 📚 Table of Contents
+## 📚 目录

- [What is Context Engineering?](#what-is-context-engineering)
- [Template Structure](#template-structure)
- [Step-by-Step Guide](#step-by-step-guide)
- [Writing Effective INITIAL.md Files](#writing-effective-initialmd-files)
- [The PRP Workflow](#the-prp-workflow)
- [Using Examples Effectively](#using-examples-effectively)
- [Best Practices](#best-practices)
+- [什么是 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)

-## What is Context Engineering?
+## 什么是 Context Engineering？

-Context Engineering represents a paradigm shift from traditional prompt engineering:
+Context Engineering 代表了相对传统 prompt engineering 的范式转变：

-### Prompt Engineering vs Context Engineering
+### Prompt Engineering 与 Context Engineering 对比

-**Prompt Engineering:**
- Focuses on clever wording and specific phrasing
- Limited to how you phrase a task
- Like giving someone a sticky note
+**Prompt Engineering：**
+- 侧重于巧妙的措辞与具体表述
+- 仅限于你如何描述一项任务
+- 就像给别人一张便利贴

-**Context Engineering:**
- A complete system for providing comprehensive context
- Includes documentation, examples, rules, patterns, and validation
- Like writing a full screenplay with all the details
+**Context Engineering：**
+- 一套用于提供全面上下文的完整系统
+- 包含文档、示例、规则、模式和验证
+- 就像撰写一份细节齐全的完整剧本

-### Why Context Engineering Matters
+### 为什么 Context Engineering 很重要

-1. **Reduces AI Failures**: Most agent failures aren't model failures - they're context failures
-2. **Ensures Consistency**: AI follows your project patterns and conventions
-3. **Enables Complex Features**: AI can handle multi-step implementations with proper context
-4. **Self-Correcting**: Validation loops allow AI to fix its own mistakes
+1. **减少 AI 失败**：大多数 agent 失败并非模型能力不足，而是上下文不足
+2. **确保一致性**：AI 会遵循你的项目模式与约定
+3. **支持复杂功能**：在充足上下文下，AI 可以处理多步骤实现
+4. **自我纠正**：验证循环让 AI 能够自行修复错误

-## Template Structure
+## 模板结构

 ```
 context-engineering-intro/
@@ -82,25 +88,25 @@ context-engineering-intro/
 └── README.md                # This file
 ```

-This template doesn't focus on RAG and tools with context engineering because I have a LOT more in store for that soon. ;)
+本模板暂不聚焦将 RAG 与工具纳入 context engineering，因为这方面我还有更多内容即将推出。;)

-## Step-by-Step Guide
+## 分步指南

-### 1. Set Up Global Rules (CLAUDE.md)
+### 1. 设置全局规则（CLAUDE.md）

-The `CLAUDE.md` file contains project-wide rules that the AI assistant will follow in every conversation. The template includes:
+`CLAUDE.md` 文件包含 AI 助手在每次对话中都会遵循的项目级规则。模板包括：

- **Project awareness**: Reading planning docs, checking tasks
- **Code structure**: File size limits, module organization
- **Testing requirements**: Unit test patterns, coverage expectations
- **Style conventions**: Language preferences, formatting rules
- **Documentation standards**: Docstring formats, commenting practices
+- **项目感知**：阅读规划文档、检查任务
+- **代码结构**：文件大小限制、模块组织
+- **测试要求**：单元测试模式、覆盖率期望
+- **风格约定**：语言偏好、格式化规则
+- **文档标准**：Docstring 格式、注释实践

-**You can use the provided template as-is or customize it for your project.**
+**你可以直接使用提供的模板，也可以按项目自行定制。**

-### 2. Create Your Initial Feature Request
+### 2. 创建初始功能需求

-Edit `INITIAL.md` to describe what you want to build:
+编辑 `INITIAL.md`，描述你想构建的内容：

 ```markdown
 ## FEATURE:
@@ -116,139 +122,139 @@ Edit `INITIAL.md` to describe what you want to build:
 [Mention any gotchas, specific requirements, or things AI assistants commonly miss]
 ```

-**See `INITIAL_EXAMPLE.md` for a complete example.**
+**完整示例见 `INITIAL_EXAMPLE.md`。**

-### 3. Generate the PRP
+### 3. 生成 PRP

-PRPs (Product Requirements Prompts) are comprehensive implementation blueprints that include:
+PRP（Product Requirements Prompts，产品需求提示）是包含以下内容的综合实现蓝图：

- Complete context and documentation
- Implementation steps with validation
- Error handling patterns
- Test requirements
+- 完整上下文与文档
+- 带验证的实现步骤
+- 错误处理模式
+- 测试要求

-They are similar to PRDs (Product Requirements Documents) but are crafted more specifically to instruct an AI coding assistant.
+它们与 PRD（Product Requirements Documents，产品需求文档）类似，但更为专门地用于指导 AI 编程助手。

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

-**Note:** The slash commands are custom commands defined in `.claude/commands/`. You can view their implementation:
- `.claude/commands/generate-prp.md` - See how it researches and creates PRPs
- `.claude/commands/execute-prp.md` - See how it implements features from PRPs
+**注意：** 这些斜杠命令是在 `.claude/commands/` 中定义的自定义命令。你可以查看其实现：
+- `.claude/commands/generate-prp.md` —— 了解其如何调研并创建 PRP
+- `.claude/commands/execute-prp.md` —— 了解其如何根据 PRP 实现功能

-The `$ARGUMENTS` variable in these commands receives whatever you pass after the command name (e.g., `INITIAL.md` or `PRPs/your-feature.md`).
+这些命令中的 `$ARGUMENTS` 变量会接收你在命令名之后传入的参数（例如 `INITIAL.md` 或 `PRPs/your-feature.md`）。

-This command will:
-1. Read your feature request
-2. Research the codebase for patterns
-3. Search for relevant documentation
-4. Create a comprehensive PRP in `PRPs/your-feature-name.md`
+该命令将：
+1. 读取你的功能需求
+2. 调研代码库中的模式
+3. 搜索相关文档
+4. 在 `PRPs/your-feature-name.md` 中创建完整的 PRP

-### 4. Execute the PRP
+### 4. 执行 PRP

-Once generated, execute the PRP to implement your feature:
+生成后，执行 PRP 以实现你的功能：

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

-The AI coding assistant will:
-1. Read all context from the PRP
-2. Create a detailed implementation plan
-3. Execute each step with validation
-4. Run tests and fix any issues
-5. Ensure all success criteria are met
+AI 编程助手将：
+1. 读取 PRP 中的全部上下文
+2. 制定详细的实现计划
+3. 逐步执行并验证
+4. 运行测试并修复问题
+5. 确保满足所有成功标准

-## Writing Effective INITIAL.md Files
+## 编写高效的 INITIAL.md 文件

-### Key Sections Explained
+### 关键章节说明

-**FEATURE**: Be specific and comprehensive
- ❌ "Build a web scraper"
- ✅ "Build an async web scraper using BeautifulSoup that extracts product data from e-commerce sites, handles rate limiting, and stores results in PostgreSQL"
+**FEATURE**：具体且全面
+- ❌ "构建一个网页爬虫"
+- ✅ "构建一个使用 BeautifulSoup 的异步网页爬虫，从电商网站提取产品数据，处理速率限制，并将结果存入 PostgreSQL"

-**EXAMPLES**: Leverage the examples/ folder
- Place relevant code patterns in `examples/`
- Reference specific files and patterns to follow
- Explain what aspects should be mimicked
+**EXAMPLES**：善用 examples/ 文件夹
+- 将相关代码模式放入 `examples/`
+- 引用应遵循的具体文件与模式
+- 说明应模仿哪些方面

-**DOCUMENTATION**: Include all relevant resources
- API documentation URLs
- Library guides
- MCP server documentation
- Database schemas
+**DOCUMENTATION**：包含所有相关资源
+- API 文档 URL
+- 库使用指南
+- MCP 服务器文档
+- 数据库 schema

-**OTHER CONSIDERATIONS**: Capture important details
- Authentication requirements
- Rate limits or quotas
- Common pitfalls
- Performance requirements
+**OTHER CONSIDERATIONS**：记录重要细节
+- 身份认证要求
+- 速率限制或配额
+- 常见陷阱
+- 性能要求

-## The PRP Workflow
+## PRP 工作流

-### How /generate-prp Works
+### /generate-prp 如何工作

-The command follows this process:
+该命令遵循以下流程：

-1. **Research Phase**
-   - Analyzes your codebase for patterns
-   - Searches for similar implementations
-   - Identifies conventions to follow
+1. **调研阶段**
+   - 分析代码库中的模式
+   - 搜索类似实现
+   - 识别应遵循的约定

-2. **Documentation Gathering**
-   - Fetches relevant API docs
-   - Includes library documentation
-   - Adds gotchas and quirks
+2. **文档收集**
+   - 获取相关 API 文档
+   - 纳入库文档
+   - 补充陷阱与注意事项

-3. **Blueprint Creation**
-   - Creates step-by-step implementation plan
-   - Includes validation gates
-   - Adds test requirements
+3. **蓝图创建**
+   - 创建分步实现计划
+   - 包含验证关卡
+   - 添加测试要求

-4. **Quality Check**
-   - Scores confidence level (1-10)
-   - Ensures all context is included
+4. **质量检查**
+   - 评估置信度（1-10）
+   - 确保包含全部上下文

-### How /execute-prp Works
+### /execute-prp 如何工作

-1. **Load Context**: Reads the entire PRP
-2. **Plan**: Creates detailed task list using TodoWrite
-3. **Execute**: Implements each component
-4. **Validate**: Runs tests and linting
-5. **Iterate**: Fixes any issues found
-6. **Complete**: Ensures all requirements met
+1. **加载上下文**：读取完整 PRP
+2. **规划**：使用 TodoWrite 创建详细任务列表
+3. **执行**：实现各个组件
+4. **验证**：运行测试与 lint
+5. **迭代**：修复发现的问题
+6. **完成**：确保满足所有要求

-See `PRPs/EXAMPLE_multi_agent_prp.md` for a complete example of what gets generated.
+生成内容的完整示例见 `PRPs/EXAMPLE_multi_agent_prp.md`。

-## Using Examples Effectively
+## 有效使用示例

-The `examples/` folder is **critical** for success. AI coding assistants perform much better when they can see patterns to follow.
+`examples/` 文件夹对成功**至关重要**。当 AI 编程助手能看到可遵循的模式时，表现会好得多。

-### What to Include in Examples
+### 示例中应包含什么

-1. **Code Structure Patterns**
-   - How you organize modules
-   - Import conventions
-   - Class/function patterns
+1. **代码结构模式**
+   - 模块组织方式
+   - import 约定
+   - 类/函数模式

-2. **Testing Patterns**
-   - Test file structure
-   - Mocking approaches
-   - Assertion styles
+2. **测试模式**
+   - 测试文件结构
+   - Mock 方法
+   - 断言风格

-3. **Integration Patterns**
-   - API client implementations
-   - Database connections
-   - Authentication flows
+3. **集成模式**
+   - API 客户端实现
+   - 数据库连接
+   - 身份认证流程

-4. **CLI Patterns**
-   - Argument parsing
-   - Output formatting
-   - Error handling
+4. **CLI 模式**
+   - 参数解析
+   - 输出格式化
+   - 错误处理

-### Example Structure
+### 示例结构

 ```
 examples/
@@ -263,34 +269,34 @@ examples/
    └── conftest.py   # Pytest configuration
 ```

-## Best Practices
+## 最佳实践

-### 1. Be Explicit in INITIAL.md
- Don't assume the AI knows your preferences
- Include specific requirements and constraints
- Reference examples liberally
+### 1. 在 INITIAL.md 中明确说明
+- 不要假设 AI 了解你的偏好
+- 包含具体的要求和约束
+- 大量引用示例

-### 2. Provide Comprehensive Examples
- More examples = better implementations
- Show both what to do AND what not to do
- Include error handling patterns
+### 2. 提供全面的示例
+- 示例越多 = 实现越好
+- 同时展示该做什么和不该做什么
+- 包含错误处理模式

-### 3. Use Validation Gates
- PRPs include test commands that must pass
- AI will iterate until all validations succeed
- This ensures working code on first try
+### 3. 使用验证关卡
+- PRP 包含必须通过测试命令
+- AI 会迭代直到所有验证通过
+- 这确保第一次就能得到可运行的代码

-### 4. Leverage Documentation
- Include official API docs
- Add MCP server resources
- Reference specific documentation sections
+### 4. 利用文档
+- 包含官方 API 文档
+- 添加 MCP 服务器资源
+- 引用具体的文档章节

-### 5. Customize CLAUDE.md
- Add your conventions
- Include project-specific rules
- Define coding standards
+### 5. 自定义 CLAUDE.md
+- 添加你的约定
+- 包含项目特定规则
+- 定义编码标准

-## Resources
+## 资源

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