project-development

项目开发方法论

此技能涵盖识别适合使用大模型处理的任务、设计有效的项目架构，以及借助 Agent 辅助开发快速迭代的原则。无论是构建批处理流水线、多 Agent 研究系统，还是交互式 Agent 应用，本方法论都适用。

此技能的工作单位是整个项目或多阶段流水线。单个工具的设计（描述、架构、错误消息）属于 tool-design。各技能的激活路由由相应技能和语料库索引负责。此技能负责项目层面的问题：是否应该使用大模型构建、流水线应采用何种形式、成本是多少，以及应该如何迭代。

何时激活

当工作单位是整个项目或流水线时，激活此技能：

• 决定大模型是否适合作为某项任务的基本工具（在编写任何代码之前评估任务与模型的匹配度）。
• 规划多阶段批处理或 Agent 流水线（获取 / 准备 / 处理 / 解析 / 渲染）。
• 估算大模型密集型项目所需的 token 数、费用和时间。
• 在项目层面选择单 Agent 还是多 Agent。
• 规划 Agent 辅助迭代（由 Agent 协助构建项目本身）。
• 在流水线契约层面设计结构化输出（跨阶段交接格式）。

对于由其他技能负责的相关工作，不要激活此技能：

• 单个工具的描述、架构、命名、响应格式和错误消息：tool-design。
• 单条轨迹的 token 效率策略（屏蔽、分区、缓存）：context-optimization。
• 在 Agent 拓扑层面决定是否将工作拆分给子 Agent：multi-agent-patterns。
• 设计自主控制循环（锁定指标、新颖性门槛、人工审批边界）：harness-engineering。

核心概念

识别任务与模型的匹配度

在编写任何代码之前，先评估任务与模型的匹配度，因为针对根本不匹配的任务构建自动化会浪费数天时间。逐项使用以下两张表评估拟议任务，以决定继续还是停止。

满足以下特征时继续：

特征	理由
综合多个来源	与基于规则的方案相比，大模型更擅长整合多个输入中的信息
基于评分标准的主观判断	评分、评估和分类等任务，其标准天然适合通过语言推理来处理
自然语言输出	当目标是生成便于人类阅读的文本时，大模型可以直接生成
容错性	单次失败不会导致整个系统崩溃，因此可以接受大模型的非确定性
批处理	项目之间无需保留对话状态，因此上下文更简洁
训练数据中包含领域知识	模型已具备相关背景知识，从而减少提示词工程的开销

满足以下特征时停止：

特征	理由
精确计算	大模型不擅长数学、计数和精确算法
实时要求	大模型的延迟过高，无法满足亚秒级响应要求
要求绝对准确	存在幻觉风险，因此无法保证 100% 准确
依赖专有数据	模型缺少必要的上下文，且无法仅通过提示词获取这些信息
存在顺序依赖	每个步骤都高度依赖上一步的结果，错误会逐步累积
要求确定性输出	相同输入必须产生完全相同的输出，而大模型无法保证这一点

手动原型步骤

在投入自动化之前，务必先通过手动测试验证任务与模型是否匹配。将一个有代表性的输入复制到模型界面中，评估输出质量，并根据结果回答以下问题：

• 模型是否具备完成此任务所需的知识？
• 模型能否按所需格式生成输出？
• 大规模应用时，预期的质量水平如何？
• 是否存在需要处理的明显失败模式？

之所以要这样做，是因为手动原型测试失败，预示自动化系统也会失败；而测试成功则既能提供质量基准，也能作为提示词设计模板。测试只需几分钟，却能避免数小时的无效开发。

流水线架构

将大模型项目设计为分阶段的流水线，因为将确定性阶段与非确定性阶段分开，有助于快速迭代并控制成本。每个阶段都应具备以下特点：

• 离散：阶段之间边界清晰，便于分别调试
• 幂等：重复运行会产生相同结果，避免重复工作
• 可缓存：中间结果持久化到磁盘，避免昂贵的重复计算
• 独立：每个阶段都可单独运行，便于选择性重新执行

采用以下标准流水线结构：

acquire -> prepare -> process -> parse -> render

1. 获取：从来源（API、文件、数据库）获取原始数据
2. 准备：将数据转换为提示词格式
3. 处理：执行大模型调用（昂贵且非确定性的步骤）
4. 解析：从大模型输出中提取结构化数据
5. 渲染：生成最终输出（报告、文件、可视化内容）

第 1、2、4、5 阶段是确定性的。第 3 阶段则是非确定性且成本高昂的。保持这种分离，因为这样一来，只有在必要时才需要重新运行昂贵的大模型阶段，同时还能快速迭代解析和渲染阶段。

文件系统作为状态机

使用文件系统跟踪流水线状态，而不是数据库或内存结构，因为文件是否存在可自然实现幂等性，也便于人工调试。

data/{id}/
  raw.json         # acquire stage complete
  prompt.md        # prepare stage complete
  response.md      # process stage complete
  parsed.json      # parse stage complete

通过检查输出文件是否存在，判断某个项目是否需要处理。删除该阶段的输出文件及后续文件，即可重新运行此阶段。直接读取中间文件进行调试。这种模式之所以有效，是因为各目录彼此独立，可轻松实现并行处理和简单缓存。

结构化输出设计

针对结构化、可解析的输出设计提示词，因为提示词设计会直接决定解析的可靠性。每个结构化提示词都应包含以下要素：

1. 章节标记：可供解析器匹配的明确标题或前缀
2. 格式示例：准确展示输出应采用的格式
3. 解析说明：说明“我会以编程方式解析此内容”，让模型优先遵循格式要求
4. 受限取值：列举选项、评分范围和固定格式

构建能够灵活处理大模型输出变化的解析器，因为大模型并不总能完美遵循指令。使用能够容忍轻微格式变化的正则表达式，在章节缺失时提供合理的默认值，并记录解析失败以供检查，而不是直接崩溃。

Agent 辅助开发

借助具备 Agent 能力的模型加速开发并快速迭代：描述项目目标和约束，让 Agent 生成初始实现，针对具体问题进行测试和迭代，再根据结果完善提示词和架构。

采用以下做法，以确保 Agent 的输出聚焦且质量较高：

• 提前提供清晰、具体的需求，减少修改次数
• 将大型项目拆分为离散组件，以便分别验证
• 在进入下一项之前测试每个组件，及早发现问题
• 让 Agent 一次专注于一项任务，避免上下文退化

成本与规模估算

开始前先估算大模型处理成本，因为规模扩大后，Token 成本会迅速累积，而等到后期才发现预算超支，会迫使你付出高昂代价返工。使用以下公式：

Total cost = (items x tokens_per_item x price_per_token) + API overhead

对于批处理，估算每个条目的输入 Token 数（提示词 + 上下文），估算每个条目的输出 Token 数（典型响应长度），乘以条目数量，再增加 20-30% 的缓冲，以应对重试和失败。

在开发过程中跟踪实际成本。如果成本大幅超出估算值，可通过截断来缩短上下文，针对简单条目使用更小的模型，缓存并复用部分结果，或添加并行处理以缩短实际耗时。

详细主题

选择单 Agent 还是多 Agent 架构

对于包含独立条目的批处理，默认采用单 Agent 流水线，因为它们更易管理、运行成本更低，也更容易调试。只有在满足以下任一条件时，才升级为多 Agent 架构：

• 需要并行探索不同方面
• 任务超出单个上下文窗口的容量
• 专用子 Agent 在基准测试中确实能提升质量

选择多 Agent 是为了隔离上下文，而不是为了拟人化角色。子 Agent 会获得全新的上下文窗口来处理专注的子任务，从而避免长时间运行的任务中上下文质量下降。

详细的架构指导请参阅 multi-agent-patterns 技能。

架构精简

从最精简的架构开始，只有在生产环境的证据证明必要时才增加复杂性，因为过度设计的脚手架往往会限制模型性能，而不是提升性能。

Vercel 的 d0 案例研究报告称，将许多专用工具精简为两个基本工具后，成功率有所提升：命令执行和 SQL（claim-project-development-vercel-d0-reduction）。文件系统 Agent 模式使用标准 Unix 工具，而不是自定义探索工具。

适合精简的情况：

• 数据层文档完善且结构一致
• 模型具备足够的推理能力
• 专用工具起到限制作用，而非赋能作用
• 维护脚手架所花的时间多于改进结果所花的时间

适合增加复杂性的情况：

• 底层数据混乱、不一致或文档不完善
• 领域需要模型所不具备的专业知识
• 安全约束要求限制 Agent 的能力
• 操作确实很复杂，且能从结构化工作流中获益

详细的工具架构指导请参阅 tool-design 技能。

迭代与重构

从一开始就为多轮架构迭代做好规划，因为大规模生产级 Agent 系统总是需要重构。Manus 自发布以来已对其 Agent 框架进行了五次重构。苦涩的教训指出，针对当前模型局限而添加的结构，会随着模型进步而成为约束。

按照以下做法构建易于变更的系统：

• 保持架构简单且不带偏见，以降低重构成本
• 跨代模型进行测试，确认支撑框架不会限制性能
• 设计能从模型改进中受益，而不是固化模型局限的系统

实用指南

项目规划模板

请按顺序遵循此模板，因为每一步都会验证相关假设，再进入下一步投入工作。

1. 任务分析

   • 明确输入和期望输出
   • 分类：综合、生成、分类或分析
   • 根据业务影响设定可接受的错误率
   • 估算每次成功完成的价值，以证明成本合理

2. 手动验证

   • 使用目标模型测试一个有代表性的示例
   • 根据要求评估输出质量和格式
   • 找出需要强化解析器或修订提示词的失败模式
   • 估算每个项目的 Token 数，以预测成本

3. 架构选择

   • 根据上述标准选择单流水线或多 Agent 架构
   • 确定所需的工具和数据源
   • 利用文件系统状态设计存储和缓存策略
   • 规划处理阶段的并行化方案

4. 成本估算

   • 按项目数 × Token 数 × 价格计算，并预留 20-30% 的缓冲
   • 估算各流水线阶段的开发时间
   • 确定基础设施需求（API 密钥、存储、计算资源）
   • 预测生产运行的持续运营成本

5. 开发计划

   • 分阶段实现，每个阶段完成后都进行测试，再继续下一阶段
   • 为每个阶段制定测试策略并明确预期输出
   • 设定与质量指标挂钩的迭代里程碑
   • 规划部署方案，并确保具备回滚能力

示例

示例 1：批量分析流水线（Karpathy 的 HN Time Capsule）

任务：回顾并评估 10 年前的 930 条 HN 讨论。

架构：

• 5 个阶段的流水线：fetch -> prompt -> analyze -> parse -> render
• 文件系统状态：data/{date}/{item_id}/，其中包含各阶段的输出文件
• 结构化输出：6 个部分，并明确格式要求
• 并行执行：15 个工作进程调用大模型

结果：总成本 58 美元，执行时间约 1 小时，输出静态 HTML。

示例 2：架构精简（Vercel d0）

任务：用于内部分析的文本转 SQL Agent。

之前：大量专用工具，实测成功率较低，平均执行时间较长。

之后：两个工具（bash + SQL），实测成功率更高，平均执行时间更短（claim-project-development-vercel-d0-reduction）。

关键见解：语义层本身就是完善的文档。Claude 只需能够直接读取文件。

详细分析请参阅案例研究。

指南

1. 在构建自动化之前，通过手动原型验证任务与模型的适配性
2. 将流水线设计为离散、幂等且可缓存的阶段
3. 使用文件系统进行状态管理和调试
4. 设计提示词，要求输出结构化、可解析，并提供明确的格式示例
5. 从最精简的架构开始；只有在证明必要时才增加复杂性
6. 尽早估算成本，并在整个开发过程中持续跟踪
7. 构建稳健的解析器，以处理大模型输出的各种变化
8. 预期架构会多次迭代，并做好规划
9. 测试脚手架对模型性能是有帮助还是有限制
10. 使用 Agent 辅助开发，以便快速迭代实现

常见问题

1. 跳过手动验证：在确认模型能完成任务之前就构建自动化，如果方法本身存在根本性缺陷，就会浪费大量时间。务必先通过模型接口运行一个有代表性的示例。
2. 单体式流水线：将所有阶段合并到一个脚本中，会让调试和迭代变得困难。应将各阶段分开，并持久化中间输出，以便独立重新运行每个阶段。
3. 过度约束模型：添加模型本可自行处理的护栏、预筛选和验证逻辑，会降低性能。保留这些机制之前，应先测试它们究竟有帮助还是有害。
4. 忽视生产环境之前的成本：规模扩大后，Token 成本会迅速累积。从一开始就进行估算和跟踪，以免预算意外超支，迫使架构返工。
5. 要求解析完美无误：期望 LLM 完美遵循格式指令，会导致系统脆弱。应构建能处理各种变化的健壮解析器，并记录失败情况以供审查。
6. 过早优化：在基础流水线正确运行之前就添加缓存、并行化和优化，会把精力浪费在迭代过程中可能被弃用的代码上。
7. 锁定模型版本：构建只能与某个特定模型版本配合使用的流水线，会形成脆弱的系统。应跨代测试模型，并抽象 LLM 调用层，以便替换模型时无需重写流水线逻辑。
8. 未评估就部署：部署 Agent 流水线却不衡量输出质量，会导致回归问题无法被发现。应在开发期间定义质量指标，并在每次更改模型或提示词前后运行评估检查。
9. 溯源信息漂移：原始输入、中间输出和最终提案分散在临时文件夹中，会导致无法审计。应将每次流水线运行的内容保存在同一目录中，包括源证据、转换记录、验证报告和决策。

集成

此技能负责项目形态和流水线决策。相邻决策由其他技能负责：

• tool-design：负责单个工具的接口层（描述、架构、响应格式、错误消息、MCP 命名空间、单个工具的整合）。如果问题是“这个具体工具应是什么样”，而不是“流水线应是什么样”，请转至此技能。
• multi-agent-patterns：负责 Agent 拓扑决策（主管式、群集式还是分层式，交接协议，跨 Agent 的上下文隔离）。此技能在项目层面决定采用单 Agent 还是多 Agent；拓扑细节由 multi-agent-patterns 负责。
• harness-engineering：负责项目周围的自主控制循环（锁定指标、新颖性门槛、运行状态机、人工审批边界）。如果问题是“如何让它无人值守地运行数天”，请转至此技能。
• context-fundamentals：负责为各阶段的提示词设计提供依据的上下文约束概念框架。
• evaluation：负责流水线运行的结果衡量和质量门槛。
• context-compression：适用于长时间运行的流水线阶段产生需要摘要的轨迹。

参考资料

内部参考：

• 案例研究 - 阅读时机：评估架构权衡或审查真实世界的流水线实现（Karpathy HN Capsule、Vercel d0、Manus 模式）
• 流水线模式 - 阅读时机：设计新的流水线阶段布局、选择缓存策略或调试阶段边界

此合集中的相关技能：

• tool-design - 工具架构与精简模式
• multi-agent-patterns - 何时使用多 Agent 架构
• evaluation - 输出评估框架

外部资源：

• Karpathy 的 HN Time Capsule 项目：https://github.com/karpathy/hn-time-capsule
• Vercel d0 架构精简：https://vercel.com/blog/we-removed-80-percent-of-our-agents-tools
• Manus 上下文工程：Peak Ji 关于上下文工程经验的博客
• Anthropic 多 Agent 研究：我们如何构建多 Agent 研究系统

---

技能元数据

创建时间：2025-12-25 最后更新：2026-05-15 作者：Agent Skills for Context Engineering Contributors 版本：1.3.0