从 INITIAL.md 开始：编写一份可被 AI 编码助手端到端执行的上下文工程需求文档-北京尧图网络

从 INITIAL.md 开始编写一份可被 AI 编码助手端到端执行的上下文工程需求文档【免费下载链接】context-engineering-introContext engineering is the new vibe coding - its the way to actually make AI coding assistants work. Claude Code is the best for this so thats what this repo is centered around, but you can apply this strategy with any AI coding assistant!项目地址: https://gitcode.com/gh_mirrors/co/context-engineering-intro本指南以仓库根目录的 INITIAL.md 为核心系统讲解上下文工程Context Engineering工作流中最关键的第一步——如何撰写一份结构化的初始需求文档。你将掌握 FEATURE、EXAMPLES、DOCUMENTATION、OTHER CONSIDERATIONS 四大区块的写作规范理解它与 CLAUDE.md、PRPProduct Requirements Prompt及/generate-prp、/execute-prp命令的协作关系并看到本仓库中多个真实业务场景的 INITIAL.md 变体最终能够独立为任何 AI 编码助手Claude Code、Pydantic AI Agent 工厂等产出高质量的需求起点。一、INITIAL.md 在上下文工程工作流中的定位本仓库 README.md 对上下文工程的定义是为 AI 编码助手工程化地构建上下文使其具备端到端完成任务的必要信息。与只关注措辞的提示工程Prompt Engineering不同上下文工程是一套完整系统涵盖文档、示例、规则、模式与验证环节。整个仓库的工作流可以抽象为一条流水线CLAUDE.md全局规则→ INITIAL.md初始需求→ /generate-prp生成 PRP→ /execute-prp执行实现CLAUDE.md 定义 AI 助手在每一个对话中都必须遵守的项目级规则项目意识、代码结构、测试要求、风格约定、文档规范INITIAL.md 是需求输入描述你想构建什么/generate-prp INITIAL.md读取需求、研究代码库、收集文档产出一份可执行的 PRP/execute-prp PRPs/your-feature-name.md依据 PRP 完成实现、测试与验证。也就是说INITIAL.md 是整个流水线的源头文件它的信息密度直接决定了 PRP 的质量与最终实现是否命中需求。仓库根目录的 INITIAL.md 全文只有四个区块却浓缩了上下文工程的核心方法论把需求翻译成AI 编码助手可检索、可对照、可执行的信息。二、拆解 INITIAL.md 的四大区块根目录 INITIAL.md 定义了四个占位区块每个区块都是一类上下文输入的收纳盒## FEATURE: [Insert your feature here] ## EXAMPLES: [Provide and explain examples that you have in the examples/ folder] ## DOCUMENTATION: [List out any documentation (web pages, sources for an MCP server like Crawl4AI RAG, etc.) that will need to be referenced during development] ## OTHER CONSIDERATIONS: [Any other considerations or specific requirements - great place to include gotchas that you see AI coding assistants miss with your projects a lot]2.1 FEATURE功能需求的唯一真相源FEATURE 区块回答要构建什么。仓库 README.md 明确给出了一组正反对照❌ 反例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 至少应包含技术选型框架/库、核心功能行为、边界约束限流、存储目标。信息越具体AI 编码助手在/generate-prp阶段做代码库模式研究与方案设计时的依据就越充分。仓库中一个完整示例位于 INITIAL_EXAMPLE.md它描述了一个 Pydantic AI 多智能体特性## FEATURE: - Pydantic AI agent that has another Pydantic AI agent as a tool. - Research Agent for the primary agent and then an email draft Agent for the subagent. - CLI to interact with the agent. - Gmail for the email draft agent, Brave API for the research agent.注意这里用分条枚举的方式给出功能清单智能体架构agent-as-tool、两个角色的职责划分、交互界面CLI、外部依赖Gmail、Brave API。这种写法比一段长文本更容易被 LLM 逐条解析并转换为 PRP 中的任务清单。2.2 EXAMPLES把参考模式喂给模型EXAMPLES 区块引用examples/目录下的代码让 AI 编码助手照着已有模式做。仓库 README.md 特别强调 examples 目录对成功是关键性的critical——AI 编码助手在能看到可模仿的模式时表现显著更好。INITIAL_EXAMPLE.md 展示了如何引用并解释示例## EXAMPLES: In the examples/ folder, there is a README for you to read to understand what the example is all about and also how to structure your own README when you create documentation for the above feature. - examples/cli.py - use this as a template to create the CLI - examples/agent/ - read through all of the files here to understand best practices for creating Pydantic AI agents that support different providers and LLMs, handling agent dependencies, and adding tools to the agent. Dont copy any of these examples directly, it is for a different project entirely. But use this as inspiration and for best practices.这段示例传递了三个关键技巧指明每个示例文件的用途use this as a template to create the CLI而不是只给路径限定参考范围Dont copy any of these examples directly防止模型机械照搬与当前项目无关的实现抽象出可迁移的模式use this as inspiration and for best practices把示例的价值从代码提升到模式。从仓库结构看示例的组织方式可以覆盖代码结构、测试、集成与 CLI 四类模式——这也是 README.md 中Using Examples Effectively一节归纳的内容。在 use-cases 子项目中这一习惯被进一步落地例如 use-cases/agent-factory-with-subagents/examples/ 下按basic_chat_agent、tool_enabled_agent、structured_output_agent、main_agent_reference等维度组织参考实现其对应的 use-cases/agent-factory-with-subagents/PRPs/INITIAL.md 中逐一列出这些示例并说明各自示范的能力点。2.3 DOCUMENTATION为模型准备可检索的知识DOCUMENTATION 区块收集开发过程中需要参考的所有外部文档与资料。根模板的注释特别提示了其中一类重要来源MCP 服务器的资料源例如 Crawl4AI RAG 这类抓取/检索服务的来源文档。仓库中 use-cases/mcp-server/PRPs/INITIAL.md 给出了一个精炼用法当所有资料已经汇总到模板文件中时只需一句话把资料在哪告诉模型——All examples are already referenced in prp_mcp_base.md - do any additional research as needed.对应模板文件 use-cases/mcp-server/PRPs/templates/prp_mcp_base.md。而 use-cases/agent-factory-with-subagents/PRPs/INITIAL.md 则展示了另一种组织方式——把精选文档直接放进仓库再引用## DOCUMENTATION: [Add any additional documentation you want it to reference - this can be curated docs you put in PRPs/ai_docs, URLs, etc.] - Pydantic AI Official Documentation: https://ai.pydantic.dev/ - Agent Creation Guide: https://ai.pydantic.dev/agents/ - Tool Integration: https://ai.pydantic.dev/tools/ - Testing Patterns: https://ai.pydantic.dev/testing/ - Model Providers: https://ai.pydantic.dev/models/仓库也实际存在PRPs/ai_docs/这类离线文档目录见 use-cases/mcp-server/PRPs/ai_docs/claude_api_usage.md 与 use-cases/mcp-server/PRPs/ai_docs/mcp_patterns.md。把关键文档固化进仓库能让模型在离线或上下文受限时依然获得权威参考这也是prp_base.md中docfile: PRPs/ai_docs/file.md字段的用途见下文 PRP 章节。2.4 OTHER CONSIDERATIONS把坑显式写出来这是最容易写满信息价值的一节。根模板注释把它定位为存放你发现 AI 编码助手经常在你项目上犯错的 gotchas的地方。从 README.md 的归纳看可以纳入的内容包括认证要求、限流/配额、常见陷阱、性能要求等。真实案例一use-cases/agent-factory-with-subagents/PRPs/INITIAL.md 中把项目级约束逐条列出## OTHER CONSIDERATIONS: - Use environment variables for API key configuration instead of hardcoded model strings - Keep agents simple - default to string output unless structured output is specifically needed - Follow the main_agent_reference patterns for configuration and providers - Always include comprehensive testing with TestModel for development真实案例二INITIAL_EXAMPLE.md 补充了交付物级别的注意事项## OTHER CONSIDERATIONS: - Include a .env.example, README with instructions for setup including how to configure Gmail and Brave. - Include the project structure in the README. - Virtual environment has already been set up with the necessary dependencies. - Use python_dotenv and load_env() for environment variables真实案例三use-cases/mcp-server/PRPs/INITIAL.md 展示了防跑偏型约束——直接声明技术路线与实施粒度## OTHER CONSIDERATIONS: - Do not use complex regex or complex parsing patterns, we use an LLM to parse PRPs. - Model and API key for Anthropic both need to be environment variables - these are set up in .dev.vars.example - Its very important that we create one task per file to keep concerns separate这三类写法分别对应代码规范约束、交付物要求、架构/实现路线约束都是 AI 编码助手最容易自作主张偏离的地方值得优先写进这一节。三、从 INITIAL.md 到 PRP两大命令的桥接INITIAL.md 本身并不被执行它通过 Claude Code 的自定义斜杠命令进入下一步。仓库 README.md 给出了完整命令序列# 生成 PRP读取需求 → 研究代码库模式 → 搜索相关文档 → 产出 PRPs/your-feature-name.md /generate-prp INITIAL.md # 执行 PRP读取全部上下文 → 制定实现计划 → 分步实现 → 运行测试修复问题 → 满足全部成功标准 /execute-prp PRPs/your-feature-name.md$ARGUMENTS变量接收命令名之后的参数如INITIAL.md或PRPs/your-feature.md。/generate-prp的产出物是 PRPProduct Requirements Prompt——比传统 PRD 更贴近直接指挥 AI 编码助手的格式。PRP 的骨架由 PRPs/templates/prp_base.md 定义其结构恰好是 INITIAL.md 四区块的放大版PRP 章节与 INITIAL.md 的对应关系Goal / Why / What Success Criteria承接 FEATURE并要求量化成功标准Documentation References含url/file/doc/docfile字段承接 DOCUMENTATION细化到具体读哪个文档的哪个部分、为什么Current / Desired Codebase tree、Known Gotchas承接 OTHER CONSIDERATIONS 并补充代码库结构上下文Implementation Blueprint任务清单、伪代码、集成点由 FEATURE EXAMPLES 推导出的实施蓝图Validation Loop三级验证与 Final Checklist对应 CLAUDE.md 的测试要求与验证闭环理念仓库提供了完整成品范例 PRPs/EXAMPLE_multi_agent_prp.md它以 INITIAL_EXAMPLE.md 的需求为输入最终长成包含 8 个任务配置环境 → Brave 搜索工具 → Gmail 工具 → 邮件子智能体 → 研究智能体 → CLI → 测试 → 文档、三级验证循环ruff/mypy → 单元测试 → 集成测试、反模式清单与 9/10 置信度评分的大文档。对比 INITIAL_EXAMPLE.md 与 PRPs/EXAMPLE_multi_agent_prp.md可以清楚看到四区块需求 → 数百行可执行蓝图的上下文放大过程。四、INITIAL.md 的领域变体一个模板多种场景本仓库展示了一个重要事实INITIAL.md 不是死模板而是可以按技术栈和项目类型演化的骨架。use-cases/下存在多个变体4.1 Pydantic AI 智能体变体agent-factory-with-subagentsuse-cases/agent-factory-with-subagents/PRPs/INITIAL.md 在四大区块基础上扩展出TOOLS、DEPENDENCIES、SYSTEM PROMPT(S)三个专有区块分别描述工具的函数签名与返回值约定Describe the tools you want for your agent(s) - functionality, arguments, what they return、RunContext 依赖API keys、DB 连接、HTTP 客户端、系统提示词设计。这是面向构建 AI 智能体场景的专用化改造其生成产物由 use-cases/agent-factory-with-subagents/PRPs/templates/prp_pydantic_ai_base.md 承接。该 use-case 的 README.md 还描述了Phase 0: Clarification阶段主智能体先提出 2~3 个针对性问题澄清需求再进入规划与并行开发——这恰好说明 INITIAL.md 也可以作为澄清对话之后的汇总产物。4.2 MCP 服务器变体mcp-serveruse-cases/mcp-server/PRPs/INITIAL.md 面向构建 MCP 服务器FEATURE 区块按目标附加功能能力清单组织LLM 驱动的 PRP 信息抽取、任务/文档/标签 CRUD、任务获取与列表、文档增改等并明确要求数据库表结构同步更新。其配套模板 use-cases/mcp-server/PRPs/templates/prp_mcp_base.md 与离线文档 use-cases/mcp-server/PRPs/ai_docs/ 共同构成了该变体的上下文底座。4.3 模板生成变体template-generatoruse-cases/template-generator/PRPs/INITIAL.md 展示了最激进的演化它不再是需求描述而是一份针对生成上下文工程模板任务的详细规格书包含 TECHNOLOGY/FRAMEWORK、TEMPLATE PURPOSE、CORE FEATURES、EXAMPLES TO INCLUDE、DOCUMENTATION TO RESEARCH、DEVELOPMENT PATTERNS、SECURITY BEST PRACTICES、COMMON GOTCHAS、VALIDATION REQUIREMENTS、INTEGRATION FOCUS、TEMPLATE COMPLEXITY LEVEL 等十余个区块并反复强调Be as specific as possible。这三种变体的共同规律是区块划分服务于模型最容易遗漏什么信息。智能体项目模型容易遗漏工具签名与依赖MCP 项目容易遗漏数据模型与 CRUD 细节模板生成项目容易遗漏安全、验证与集成范围——INITIAL.md 的演化就是把这些问题前置到需求阶段。五、编写高质量 INITIAL.md 的最佳实践综合根模板、README 与各 use-case 的实际写法可以沉淀出以下可复用的实践清单FEATURE 要带约束地具体指名框架、行为、边界限流、存储、异步等参考 INITIAL_EXAMPLE.md 的分条枚举风格EXAMPLES 要给路径用途边界说明每个示例文件解决什么问题、哪些方面要模仿、哪些不能照抄Dont copy… use this as inspirationDOCUMENTATION 要可追溯优先把关键文档固化到仓库如PRPs/ai_docs/URL 与docfile并存让模型即使离线也有据可查OTHER CONSIDERATIONS 要写模型容易犯错的地方环境变量规范、交付物清单、架构路线、实现粒度如one task per file都是高价值内容不要假设 AI 知道你的偏好README 的 Best Practices 第一条就是 Dont assume the AI knows your preferences所有约束要显式写出示例宁多勿少README 指出 More examples better implementations并建议同时展示该做什么与不该做什么让验证成为闭环PRP 模板 PRPs/templates/prp_base.md 的反模式清单提供了反面参照——Dont skip validation because it should work、Dont ignore failing tests - fix them这些约束最好也在 OTHER CONSIDERATIONS 中显式声明。六、与配套文件的协同关系INITIAL.md 不是孤立的文档它与仓库内其他文件构成完整协作网络CLAUDE.md全局规则规定永远不要臆断缺失的上下文不确定就要提问绝不凭空编造库或函数引用代码前必须先确认文件路径与模块名存在等 AI 行为规则——这些规则约束了模型在解读 INITIAL.md 时的自由度也是AI 编码助手可用的前提保障PRPs/templates/prp_base.md 与 PRPs/EXAMPLE_multi_agent_prp.md分别提供 PRP 的骨架与成品范例是验证你的 INITIAL.md 是否喂得饱PRP 的对照物——如果从四区块出发无法推导出 Goal/Success Criteria/任务清单说明需求还不够具体examples/目录承接 EXAMPLES 区块的引用对象是上下文工程中模式传递的核心载体CLI 命令体系use-cases/ai-coding-workflows-foundation/commands/create-plan.md 与 use-cases/ai-coding-workflows-foundation/commands/execute-plan.md 展示了同一思想的另一套实现/create-plan与/execute-plan其 Step 1 Read and Analyze Requirements 同样从需求文件起步并强调在生成计划前要先用 codebase-analyst 智能体做模式分析验证体系validation/ 目录下的 README.md 与 ultimate_validate_command.md 说明了最终验证命令如何系统化地检查生成结果——这呼应了 INITIAL.md 中把成功标准与约束写清楚的价值只有需求可度量验证才有对象。七、结语INITIAL.md 只有短短数行占位符却是整个上下文工程流水线的需求原点。它的四区块结构——FEATURE、EXAMPLES、DOCUMENTATION、OTHER CONSIDERATIONS——本质上是在强制你回答四个问题做什么、参照什么、依据什么、注意什么。本仓库用 INITIAL_EXAMPLE.md 和多组 use-case 变体证明一旦这四个问题的答案足够具体AI 编码助手就能通过/generate-prp将其放大为带验证闭环的可执行 PRP最终由/execute-prp交付带测试、带文档、满足成功标准的实现。对你自己的项目而言从今天起把每一次新需求都写成一份结构化的 INITIAL.md就是迈向让 AI 真正可靠地完成端到端开发的第一步。【免费下载链接】context-engineering-introContext engineering is the new vibe coding - its the way to actually make AI coding assistants work. Claude Code is the best for this so thats what this repo is centered around, but you can apply this strategy with any AI coding assistant!项目地址: https://gitcode.com/gh_mirrors/co/context-engineering-intro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

从 INITIAL.md 开始：编写一份可被 AI 编码助手端到端执行的上下文工程需求文档

相关推荐

图解Profile原理：3步搞定性能瓶颈实战

C#获取问财选股数据：协议解析、v值生成与WinForms集成实战

操作系统选型指南：Windows、UNIX、Linux内核差异与国产化适配实践

更多资讯

2026年公司网站制作哪家好，这几家可别错过哦！

SpringBoot+Vue社区医疗系统开发实践

做教育小程序用什么工具好？先别急着点“立即创建”

FastAPI项目集成Tortoise-ORM：异步原生ORM的工程实践指南

啪啪网面试高频题保姆级教程：3天吃透考点避坑指南

VCS仿真提速实战：debug_access分级选型与编译运行优化指南

今日更新

2k显示屏性能优化踩坑：版本升级后API全变了，这份源码解析救了我

3步搞定美眉图实战项目，告别官方文档抓不住重点

3步搞定黄金大劫案项目搭建从入门到精通

本周精选

深入解析Transformer多头注意力机制与工程优化

OpenClaw 的 Skills 跑学习任务，模型通道改到 TaoToken 通道行不行？

ChatGPT报错Oops, an error occurred! 全链路排查指南

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？