pydantic-ai-planner 子代理深度解析：用 MVP 思维驱动 Pydantic AI 需求规划（Agent Factory 实战指南）

文档教程提示工程人工智能【免费下载链接】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点击查看免费下载本篇指南围绕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的声明如下字段值作用namepydantic-ai-planner子代理唯一标识供主 Agent 在 Phase 1 按名调用description需求收集与 Pydantic AI Agent 开发规划专家USE PROACTIVELYwhen user requests to build any AI agent决定主 Agent 何时自动激活它USE PROACTIVELY表示当用户请求构建 Agent 时应主动启用toolsRead, Write, Grep, Glob, Task, TodoWrite, WebSearch允许它阅读既有代码、写入规划文档、全局搜索、管理任务清单以及联网研究类似 Agent 模式colorblue终端交互中的显示配色仅用于视觉区分值得注意的细节该子代理的description末尾明确写着Works autonomously without user interaction——这既是身份声明也是主 Agent 调度时的行为契约。仓库的 CLAUDE.md 中 Phase 1 的定义与此一致Mode: AUTONOMOUS - Works without user interaction其哲学正是 SIMPLE, FOCUSED requirementsMVP mindset。三、核心理念五条 Simplicity PrinciplesMVP 哲学pydantic-ai-planner的全部行为围绕一条核心哲学展开Start simple, make it work, then iterate.先做简单、跑通、再迭代它明确把避免过度工程作为第一原则具体化为五条可执行准则Start with MVP聚焦能立即交付价值的核心功能Avoid Premature Optimization不要以防万一地添加功能Single Responsibility每个 Agent 只把一件事做好Minimal Dependencies只添加绝对必要的依赖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 Analysisplanner 的首要任务是从上下文里剥离出核心问题识别 Agent 要解决的 CORE problem通常只有 1-2 个主功能只抽取必要需求忽略次要细节做出简单、务实的默认假设使用单一模型提供商不做复杂 fallback从基础错误处理起步除非明确需要结构化数据否则默认字符串输出最小化外部依赖。4.2 Pydantic AI 架构规划基于收集到的需求planner 需要给出三项架构决策Agent 类型分类四选一类型定位Chat Agent带记忆/上下文的对话式 AgentTool-Enabled Agent侧重外部集成的工具型 AgentWorkflow Agent多步骤编排型 AgentStructured Output Agent复杂数据校验的 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 whats absolutely needed] ## Environment Variables bash LLM_API_KEYyour-api-key [OTHER_API_KEY]if-neededSuccess 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 criticalRequired 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 | 选最常见/最易接入的选项如搜索用 BraveLLM 用 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 是流水线中所有后续环节的共同输入prompt-engineer基于需求设计系统 prompt产出prompts.mdtool-integrator根据集成需求开发工具规格产出tools.mddependency-manager搭建依赖与配置产出dependencies.mdMain Claude Code依据四份规划文档实现 Agentpydantic-ai-validator对照成功标准编写测试并验证。在编排层面CLAUDE.md 规定 planner 的调用时机位于 Phase 0澄清之后主 Agent 在用户回答 2-3 个针对性问题后确定 Agent 文件夹名snake_case创建agents/[AGENT_FOLDER_NAME]/目录然后以完全相同的文件夹名调用所有子代理并明确指示 Output to agents/[AGENT_FOLDER_NAME]/。同时强烈建议在调用前更新 Archon 任务 1Requirements Analysis的状态以便追踪进度。八、实战示例从web 搜索 Agent到 INITIAL.md文档中给出的完整自主运行示例输入用户请求I want to build an AI agent that can search the web澄清信息Should summarize results, use Brave APIplanner 的自主过程分析请求与澄清信息对缺失细节做出假设将自动处理速率限制初始独立运行返回摘要型字符串输出默认搜索通用网页创建包含全部需求的完整 INITIAL.md在需求中清晰记录所有假设。输出一份完整、无需进一步交互的 INITIAL.md。这个输入 → 假设 → 结构化需求文档的模式在仓库中已有真实落地案例rag_agent的 planning/INITIAL.md 就是语义搜索 Agent 的完整需求文档包含执行摘要、Agent 分类Tool-Enabled Agent with structured output、功能需求语义搜索/混合搜索自动选择/结果摘要、模型配置openai:gpt-4o-minitext-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 文件复用成本极低复制 .claude/agents/pydantic-ai-planner.md 到你的项目.claude/agents/目录按需调整 frontmatter如修改tools权限、color、description中的触发条件保持 INITIAL.md 模板结构与仓库其他子代理一致——文档明确警告Maintain consistent document structure for pipeline compatibility保持一致的文档结构以保证流水线兼容下游子代理都依赖这份结构做解析若你有自定义领域需求如数据库 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 分钟交付一个带测试的 AgentREADME 所述的根基所在——所有并行开发、测试与交付的效率都建立在规划阶段这份简洁而完备的 INITIAL.md 之上。赞分享文档教程提示工程人工智能【免费下载链接】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点击查看免费下载相关推荐Pydantic AI 实战用 TwelveLabs Pegasus 打造视频理解 AgentPydantic AI 实战用 TwelveLabs Pegasus 打造视频理解 Agent 导读 本文基于 pydantic ai 仓库中的官方示例 do人工智能大模型AI Agent工具调用MCP ClientsPydantic AI Web Chat UI 实战指南用 to_web() 与 clai web 在浏览器里驱动 AgentPydantic AI Web Chat UI 实战指南用 to_web 与 clai web 在浏览器里驱动 Agent 本指南以 Pydantic AI人工智能大模型AI Agent工具调用MCP ClientsHindsight Pydantic AI 集成 0.4.20 实战为 Pydantic AI Agent 赋予持久化记忆Hindsight Pydantic AI 集成 0.4.20 实战为 Pydantic AI Agent 赋予持久化记忆 导读 本篇文章围绕 Hindsig人工智能AI AgentAgent 记忆MCP 服务上一篇一键解锁Zotero插件市场告别繁琐的插件管理开启高效学术研究之旅下一篇SOCD Cleaner彻底解决键盘方向冲突的终极游戏神器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考