企业官网建设流程全解析

• 文档
• 教程
• 提示工程
• 人工智能

本篇指南围绕context-engineering-intro仓库中 AI Agent Factory（基于 Claude Code 子代理自动构建 Pydantic AI Agent 的编排框架）的核心子代理pydantic-ai-planner展开，完整解析它的角色声明、MVP 需求哲学、自主工作协议、INITIAL.md 产出规范，以及它与流水线中其他子代理的衔接方式。读完本文，你将掌握如何编写、部署并复用一个"全自主需求规划官"式 Claude Code 子代理，为后续 prompt 设计、工具集成、依赖配置与测试验证提供高质量输入。

一、pydantic-ai-planner 是什么：Agent Factory 的"需求规划官"

在 AI Agent Factory 的六阶段流水线（Clarification → Requirements → Parallel Development → Implementation → Validation → Delivery）中，pydantic-ai-planner承担着Phase 1（需求文档化）这一最关键的起点职责。它的定位在仓库的 README 中描述得很清楚：

Creates minimal, focused requirements documents (INITIAL.md) with MVP mindset. Analyzes user needs and produces clear specifications for agent development.

它的工作方式是全自主（Autonomous）：不需要与用户反复交互，而是基于用户请求与澄清阶段收集到的上下文，直接做出符合最佳实践的合理假设，最终产出一份结构统一、可直接驱动下游开发的INITIAL.md需求文档。整个规划子代理的完整定义保存在 .claude/agents/pydantic-ai-planner.md，这是 Claude Code 子代理的标准 Markdown 定义文件。

二、子代理声明解析：frontmatter 与工具权限

Claude Code 的子代理通过文件头部的 YAML frontmatter 声明身份，pydantic-ai-planner的声明如下：

值得注意的细节：该子代理的description末尾明确写着"Works autonomously without user interaction"——这既是身份声明，也是主 Agent 调度时的行为契约。仓库的 CLAUDE.md 中 Phase 1 的定义与此一致：Mode: AUTONOMOUS - Works without user interaction，其哲学正是 SIMPLE, FOCUSED requirements（MVP mindset）。

三、核心理念：五条 Simplicity Principles（MVP 哲学）

pydantic-ai-planner的全部行为围绕一条核心哲学展开：

"Start simple, make it work, then iterate."（先做简单、跑通、再迭代）

它明确把"避免过度工程"作为第一原则，具体化为五条可执行准则：

1. Start with MVP：聚焦能立即交付价值的核心功能；
2. Avoid Premature Optimization：不要"以防万一"地添加功能；
3. Single Responsibility：每个 Agent 只把一件事做好；
4. Minimal Dependencies：只添加绝对必要的依赖；
5. Clear Over Clever：简单可读的方案优先于复杂架构。

这条哲学在仓库的全局规则中同样被反复强调：CLAUDE.md 的 Phase 2 中，prompt-engineer 被要求产出 100-300 词的简单静态 prompt、tool-integrator 被限定只规划 2-3 个必要工具、dependency-manager 被要求"最小化配置、单一模型提供商、无 fallback"。也就是说，planner 的 MVP 输出是整个流水线"简洁"基调的源头——如果需求规划阶段就铺张，下游每个阶段都会被放大拖累。

四、三大核心职责

4.1 自主需求分析（Autonomous Requirements Analysis）

planner 的首要任务是从上下文里剥离出核心问题：

• 识别 Agent 要解决的 CORE problem（通常只有 1-2 个主功能）；
• 只抽取必要需求，忽略次要细节；
• 做出简单、务实的默认假设：
  • 使用单一模型提供商（不做复杂 fallback）；
  • 从基础错误处理起步；
  • 除非明确需要结构化数据，否则默认字符串输出；
  • 最小化外部依赖。

4.2 Pydantic AI 架构规划

基于收集到的需求，planner 需要给出三项架构决策：

Agent 类型分类（四选一）：

模型提供商策略：确定主模型（OpenAI / Anthropic / Gemini 等）、是否配置 fallback 模型、以及 token/成本优化考量。

工具需求：识别所需外部工具、定义工具接口与参数、规划错误处理策略。

4.3 需求文档产出：INITIAL.md 模板

这是 planner 的最终交付物。它必须把需求写入agents/[agent_name]/planning/INITIAL.md，并使用下面这份结构固定的模板（这是整个 Agent Factory 流水线的数据契约，下游所有子代理都依赖其结构稳定）：

# [Agent Name] - Simple Requirements ## What This Agent Does [1-2 sentences describing the core purpose] ## Core Features (MVP) 1. [Primary feature - the main thing it does] 2. [Secondary feature - if absolutely necessary] 3. [Third feature - only if critical] ## Technical Setup ### Model - **Provider**: [openai/anthropic/gemini] - **Model**: [specific model name] - **Why**: [1 sentence justification] ### Required Tools 1. [Tool name]: [What it does in 1 sentence] 2. [Only list essential tools] ### External Services - [Service]: [Purpose] - [Only list what's absolutely needed] ## Environment Variables ```bash LLM_API_KEY=your-api-key [OTHER_API_KEY]=if-needed

Success Criteria

• [Main functionality works]
• [Handles basic errors gracefully]
• [Returns expected output format]

Assumptions Made

• [List any assumptions to keep things simple]
• [Be transparent about simplifications]

Generated: [Date] Note: This is an MVP. Additional features can be added after the basic agent works.

模板的设计意图很明确：`Core Features` 最多只列 2-3 项（"only if critical"）；`Required Tools` 只列必需的；`Assumptions Made` 要求对简化行为保持透明；结尾的 `Note` 则向后续所有子代理传达"这是 MVP，后续可迭代"的基调。这份模板与仓库根目录下 [PRPs/INITIAL.md](https://link.gitcode.com/i/45d4ec50b8b4cfc607e521e7f50fa3c8)（面向编码助手的通用需求模板）一脉相承，后者同样强调"Keep agents simple - default to string output unless structured output is specifically needed"。 ## 五、自主工作协议：分析与假设的艺术 planner 的三个工作阶段在文档中被拆解为： ### 分析阶段（Analysis Phase） 1. 解析用户的 Agent 请求及任何澄清信息； 2. 识别显式与隐式需求； 3. 必要时研究类似的 Agent 模式（借助其 WebSearch 工具）。 ### 假设阶段（Assumption Phase） 对于需求中的任何空缺，按以下默认策略做出"聪明假设"： | 空缺项 | 默认策略 | | --- | --- | | 未指定 API | 选最常见/最易接入的选项（如搜索用 Brave，LLM 用 OpenAI） | | 输出格式不明确 | 简单 Agent 默认字符串，数据密集型 Agent 默认结构化输出 | | 未提及安全 | 应用标准最佳实践（env vars、输入校验） | | 使用模式不明确 | 假设交互式/按需使用 | | 未指定性能 | 可靠性优先于速度 | ### 文档化阶段（Documentation Phase） 1. 创建 `agents` 目录结构； 2. 生成包含**全部假设记录**、**架构决策理由**、**可后续调整的默认配置**的完整 INITIAL.md； 3. 校验所有需求都能用 Pydantic AI 实现； 4. 标记任何需要特别关注的需求。 ## 六、输出标准：目录结构与质量检查清单 planner 产出的目录组织遵循 Agent Factory 的统一规范： ```text agents/ └── [agent_name]/ ├── planning/ # All planning documents go here │ ├── INITIAL.md # Your output │ ├── prompts.md # (Created by prompt-engineer) │ ├── tools.md # (Created by tool-integrator) │ └── dependencies.md # (Created by dependency-manager) └── [implementation files created by main agent]

在最终确定 INITIAL.md 之前，planner 必须通过以下质量清单（Quality Checklist）：

• ✅ 所有用户需求已被捕获
• ✅ 技术可行性已验证
• ✅ Pydantic AI 模式已识别
• ✅ 外部依赖已记录
• ✅ 成功标准可度量
• ✅ 安全考量已覆盖

这与 CLAUDE.md 中 Phase 1 的 Quality Gate 相互印证：INITIAL.md 必须包含 Agent 分类与类型、功能需求、技术需求、外部依赖、成功标准五大要素。

七、与 Agent Factory 的集成：一份 INITIAL.md 驱动整条流水线

planner 产出的 INITIAL.md 是流水线中所有后续环节的共同输入：

1. prompt-engineer：基于需求设计系统 prompt（产出prompts.md）；
2. tool-integrator：根据集成需求开发工具规格（产出tools.md）；
3. dependency-manager：搭建依赖与配置（产出dependencies.md）；
4. Main Claude Code：依据四份规划文档实现 Agent；
5. pydantic-ai-validator：对照成功标准编写测试并验证。

在编排层面，CLAUDE.md 规定 planner 的调用时机位于 Phase 0（澄清）之后：主 Agent 在用户回答 2-3 个针对性问题后，确定 Agent 文件夹名（snake_case），创建agents/[AGENT_FOLDER_NAME]/目录，然后以完全相同的文件夹名调用所有子代理，并明确指示 "Output to agents/[AGENT_FOLDER_NAME]/"。同时强烈建议在调用前更新 Archon 任务 1（"Requirements Analysis"）的状态，以便追踪进度。

八、实战示例：从"web 搜索 Agent"到 INITIAL.md

文档中给出的完整自主运行示例：

输入：

• 用户请求："I want to build an AI agent that can search the web"
• 澄清信息："Should summarize results, use Brave API"

planner 的自主过程：

1. 分析请求与澄清信息；
2. 对缺失细节做出假设：
   • 将自动处理速率限制；
   • 初始独立运行；
   • 返回摘要型字符串输出；
   • 默认搜索通用网页；
3. 创建包含全部需求的完整 INITIAL.md；
4. 在需求中清晰记录所有假设。

输出：一份完整、无需进一步交互的 INITIAL.md。

这个"输入 → 假设 → 结构化需求文档"的模式，在仓库中已有真实落地案例：rag_agent的 planning/INITIAL.md 就是语义搜索 Agent 的完整需求文档，包含执行摘要、Agent 分类（Tool-Enabled Agent with structured output）、功能需求（语义搜索/混合搜索自动选择/结果摘要）、模型配置（openai:gpt-4o-mini+text-embedding-3-small）、工具规格（semantic_search、hybrid_search、auto_search）、环境变量、成功标准、假设清单等——与本文第五节模板完全对应。它的兄弟文档 prompts.md、tools.md、dependencies.md 则分别展示了 prompt-engineer、tool-integrator、dependency-manager 如何消费 INITIAL.md，可以作为理解流水线协同的完整参考。

九、如何复用与改造这个规划子代理

由于 Claude Code 子代理就是一个 Markdown 文件，复用成本极低：

1. 复制 .claude/agents/pydantic-ai-planner.md 到你的项目.claude/agents/目录；
2. 按需调整 frontmatter（如修改tools权限、color、description中的触发条件）；
3. 保持 INITIAL.md 模板结构与仓库其他子代理一致——文档明确警告"Maintain consistent document structure for pipeline compatibility"（保持一致的文档结构以保证流水线兼容），下游子代理都依赖这份结构做解析；
4. 若你有自定义领域需求（如数据库 Agent、研究 Agent），可以参照 PRPs/templates/prp_pydantic_ai_base.md 提供的结构化模板来组织需求，再交给 planner 收敛为 INITIAL.md。

改造时需要坚守的原则（文档 "Remember" 部分）：

• 全程自主运行，绝不提问，而是做出聪明假设；
• 在需求文档中清晰记录全部假设；
• 你是 Agent Factory 流水线的地基，这里的彻底性决定下游质量；
• 始终对照 Pydantic AI 能力验证需求；
• 产出可实施、可操作的需求，而非含糊的描述；
• 信息缺失时，基于最佳实践选择合理默认值。

十、小结：为什么"规划先行"决定 Agent Factory 的成败

pydantic-ai-planner的价值不在于它写了多少代码，而在于它用一套固定结构 + MVP 哲学 + 透明假设的机制，把模糊的用户意图转化为下游五个环节都能直接消费的规格。这份文档提醒我们：在 AI 辅助编码的场景下，高质量的需求规划是自动化流水线可靠性的第一道也是最重要的一道闸门。理解了这个子代理，你就理解了 Agent Factory 之所以能"10-15 分钟交付一个带测试的 Agent"（README 所述）的根基所在——所有并行开发、测试与交付的效率，都建立在规划阶段这份简洁而完备的 INITIAL.md 之上。

• 文档
• 教程
• 提示工程
• 人工智能