项目开发方法论Skill project-development

项目开发方法论

这项技能涵盖了识别适合LLM处理的任务、设计有效的项目架构以及使用代理辅助开发快速迭代的原则。无论是构建批处理管道、多代理研究系统还是交互式代理应用，该方法论都适用。

何时激活

在以下情况下激活这项技能：

• 启动可能从LLM处理中受益的新项目
• 评估任务是否适合代理而非传统代码
• 设计LLM驱动应用的架构
• 规划具有结构化输出的批处理管道
• 选择单代理和多代理方法
• 估算LLM重型项目的成本和时间线

核心概念

任务-模型适配识别

并非每个问题都能从LLM处理中受益。任何项目的第一步是评估任务特征是否与LLM的优势相匹配。在编写任何代码之前应该进行此评估。

适合LLM的任务具有以下特征：

特征	为什么适合
跨源合成	LLM擅长结合多个输入的信息
带有评分标准的主观判断	LLM处理评分、评估和分类的标准
自然语言输出	当目标是人类可读文本而非结构化数据时
容错性	个别失败不会破坏整个系统
批处理	不需要项目之间的对话状态
训练中的领域知识	模型已经具有相关上下文

不适合LLM的任务具有以下特征：

特征	为什么失败
精确计算	数学、计数和精确算法不可靠
实时要求	LLM延迟对于亚秒级响应太高
完美准确性要求	幻觉风险使得100%准确性不可能
专有数据依赖	模型缺乏必要的上下文
序列依赖性	每一步严重依赖前一个结果
确定性输出要求	相同的输入必须产生相同的输出

评估应通过手动原型制作进行：将一个代表性示例直接与目标模型进行测试，然后再构建任何自动化。

手动原型步骤

在投资自动化之前，使用手动测试验证任务-模型适配。将一个代表性输入复制到模型界面中。评估输出质量。这只需要几分钟，可以避免浪费开发时间。

这种验证回答了关键问题：

• 模型是否具有执行此任务所需的知识？
• 模型能否以您需要的格式产生输出？
• 您应该期望在规模上获得什么质量水平？
• 有没有明显的失败模式需要解决？

如果手动原型失败，自动化系统将会失败。如果成功，您就有了比较的基线和提示设计的模板。

管道架构

LLM项目受益于分阶段的管道架构，每个阶段都是：

• 离散：阶段之间有明确的界限
• 幂等：重新运行产生相同的结果
• 可缓存：中间结果保存到磁盘
• 独立：每个阶段可以单独运行

规范管道结构：

获取 → 准备 → 处理 → 解析 → 渲染

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

阶段1、2、4和5是确定性的。阶段3是非确定性的且昂贵的。这种分离允许仅在必要时重新运行昂贵的LLM阶段，同时快速迭代解析和渲染。

文件系统作为状态机

使用文件系统跟踪管道状态，而不是数据库或内存结构。每个处理单元获得一个目录。每个阶段的完成由文件存在标记。

data/{id}/
├── raw.json         # 获取阶段完成
├── prompt.md        # 准备阶段完成
├── response.md      # 处理阶段完成
└── parsed.json      # 解析阶段完成

要检查一个项目是否需要处理：检查输出文件是否存在。要重新运行一个阶段：删除其输出文件和下游文件。要调试：直接读取中间文件。

这种模式提供：

• 自然幂等性（文件存在门控执行）
• 易于调试（所有状态都是人类可读的）
• 简单的并行化（每个目录是独立的）
• 简单的缓存（文件在运行之间持久）

结构化输出设计

当LLM输出必须被程序解析时，提示设计直接决定了解析的可靠性。提示必须用例子指定确切的格式要求。

有效的结构规范包括：

1. 节标记：用于解析的显式标题或前缀
2. 格式示例：展示确切的输出应该是什么样子
3. 理由披露：“我将程序化地解析这个”
4. 限制值：枚举选项、分数范围、格式

示例提示结构：

分析以下内容，并以完全这种格式提供您的回应：

## 摘要
[您的摘要在这里]

## 评分
评分：[1-10]

## 细节
- 关键点1
- 关键点2

严格遵循此格式，因为我将程序化地解析它。

解析代码必须能够优雅地处理变体。LLM并不完美地遵循指令。构建解析器：

• 使用足够灵活的正则表达式模式来处理小的格式变化
• 当部分缺失时提供合理的默认值
• 日志记录解析失败以供后续审查而不是崩溃

代理辅助开发

现代代理能力模型可以显著加速开发。模式是：

1. 描述项目目标和约束
2. 让代理生成初始实现
3. 在特定失败上进行测试和迭代
4. 根据结果完善提示和架构

这是关于快速迭代的：生成、测试、修复、重复。代理处理样板和初始结构，而您专注于特定领域的要求和边缘情况。

有效的代理辅助开发的关键实践：

• 提前提供清晰、具体的要求
• 将大型项目分解为离散组件
• 在进入下一个组件之前测试每个组件
• 保持代理一次只关注一个任务

成本和规模估算

LLM处理具有可预测的成本，应在开始之前进行估算。公式：

总成本 = (项目 × 每个项目的令牌 × 每个令牌的价格) + API开销

对于批处理：

• 估计每个项目的输入令牌（提示+上下文）
• 估计每个项目的输出令牌（典型的响应长度）
• 乘以项目数量
• 增加20-30%的缓冲区以应对重试和失败

在开发过程中跟踪实际成本。如果成本显著超过估计，重新评估方法。考虑：

• 通过截断减少上下文长度
• 对于较简单的项目使用较小的模型
• 缓存和重用部分结果
• 并行处理以减少墙钟时间（而不是令牌成本）

详细主题

选择单代理与多代理架构

单代理管道适用于：

• 独立项目的批处理
• 项目之间不互动的任务
• 更简单的成本和复杂性管理

多代理架构适用于：

• 平行探索不同方面
• 超出单个上下文窗口容量的任务
• 当专门的子代理提高质量时

多代理的主要原因是上下文隔离，而不是角色拟人化。子代理为专注的子任务获得新的上下文窗口。这防止了长运行任务中的上下文退化。

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

架构简化

从最小架构开始。只有在证明必要时才增加复杂性。生产证据表明，去除专用工具通常会提高性能。

Vercel的d0代理通过从17个专用工具减少到2个原语，将成功率从80%提高到100%：bash命令执行和SQL。文件系统代理模式使用标准Unix实用程序（grep、cat、find、ls）而不是定制的探索工具。

简化优于复杂性时：

• 您的数据层文档齐全且结构一致
• 模型具有足够的推理能力
• 您的专用工具限制而不是促进
• 您花费更多的时间维护脚手架而不是提高结果

复杂性必要时：

• 您的底层数据混乱、不一致或文档不良
• 领域需要模型缺乏的专业知识
• 安全约束要求限制代理能力
• 操作确实复杂，受益于结构化的工作流程

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

迭代和重构

预计会重构。大规模生产代理系统需要多次架构迭代。Manus自推出以来重构了他们的代理框架五次。Bitter Lesson表明，为当前模型限制添加的结构随着模型的改进成为限制。

为变化而构建：

• 保持架构简单且无偏见
• 在模型优势上测试，以验证您的马具是否限制了性能
• 设计系统以从模型改进中受益，而不是锁定限制

实践指导

项目计划模板

1. 任务分析

   • 输入是什么？期望的输出是什么？
   • 这是合成、生成、分类还是分析？
   • 可接受的错误率是多少？
   • 每次成功完成的价值是多少？

2. 手动验证

   • 使用目标模型测试一个示例
   • 评估输出质量和格式
   • 识别失败模式
   • 估计每个项目的令牌

3. 架构选择

   • 单管道与多代理
   • 所需的工具和数据源
   • 存储和缓存策略
   • 并行化方法

4. 成本估算

   • 项目 × 令牌 × 价格
   • 开发时间
   • 基础设施要求
   • 持续运营成本

5. 开发计划

   • 阶段性实施
   • 每个阶段的测试策略
   • 迭代里程碑
   • 部署方法

避免的反模式

跳过手动验证：在验证模型能否执行任务之前构建自动化会浪费大量时间，当方法是根本错误的。

单体管道：将所有阶段合并为一个脚本，使调试和迭代变得困难。用持久的中间输出分离阶段。

过度限制模型：添加护栏、预过滤和验证逻辑，模型本身可以处理。测试您的脚手架是否帮助或伤害。

直到生产才考虑成本：令牌成本在规模上迅速累积。从一开始就估计和跟踪。

完美解析要求：期望LLM完美遵循格式指令。构建能够处理变化的强大解析器。

过早优化：在基本管道正确工作之前添加缓存、并行化和优化。

示例

示例1：批处理分析管道（Karpathy的HN时间胶囊）

任务：用事后评分分析10年前的930个HN讨论。

架构：

• 5阶段管道：获取 → 提示 → 分析 → 解析 → 渲染
• 文件系统状态：data/{date}/{item_id}/，带有阶段输出文件
• 结构化输出：6个部分，带有明确的格式要求
• 并行执行：15个LLM调用工作

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

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

任务：内部分析的文本到SQL代理。

之前：17个专用工具，80%成功率，平均执行时间274秒。

之后：2个工具（bash + SQL），100%成功率，平均执行时间77秒。

关键见解：语义层已经是很好的文档。Claude只需要直接访问文件。

有关详细分析，请参见案例研究。

指南

1. 在构建自动化之前，通过手动原型制作验证任务-模型适配
2. 将管道结构化为离散的、幂等的、可缓存的阶段
3. 使用文件系统进行状态管理和调试
4. 设计提示以获得结构化、可解析的输出，并提供明确格式示例
5. 从最小架构开始；只有在证明必要时才增加复杂性
6. 从早期开始估算成本，并在开发过程中跟踪
7. 构建能够处理LLM输出变化的强大解析器
8. 预计并计划多次架构迭代
9. 测试脚手架是否有助于或限制模型性能
10. 使用代理辅助开发以快速迭代实施

集成

这项技能连接到：

• context-fundamentals - 理解上下文约束以设计提示
• tool-design - 在管道中为代理系统设计工具
• multi-agent-patterns - 使用多代理与单管道时
• evaluation - 评估管道输出和代理性能
• context-compression - 当管道超出限制时管理上下文

参考

内部参考：

• 案例研究 - Karpathy HN Capsule, Vercel d0, Manus patterns
• Pipeline Patterns - 详细的管道架构指导

相关技能在此集合中：

• tool-design - 工具架构和简化模式
• multi-agent-patterns - 使用多代理架构时
• evaluation - 输出评估框架

外部资源：

• Karpathy的HN时间胶囊项目：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多代理研究：我们如何构建我们的多代理研究系统

---

技能元数据

创建：2025-12-25 最后更新：2025-12-25 作者：上下文工程代理技能贡献者 版本：1.0.0