project-development

项目开发方法论

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

适用场景

在以下情况启用本技能：

• 启动一个可能受益于大模型处理的新项目
• 评估某项任务是否适合交由 Agent 处理，而非使用传统代码
• 设计由大模型驱动的应用架构
• 规划具有结构化输出的批处理流水线
• 在单 Agent 和多 Agent 方案之间做出选择
• 估算大模型密集型项目的成本和时间

核心概念

识别任务与模型的匹配度

并非所有问题都能从大模型处理中受益。任何项目的第一步，都是评估任务特征是否与大模型的优势相符。应在编写代码之前完成这项评估。

适合大模型处理的任务具有以下特征：

特征	适用原因
跨来源综合信息	大模型擅长整合多个输入中的信息
基于标准进行主观判断	大模型能够依据标准进行评分、评估和分类
自然语言输出	目标是生成便于人阅读的文本，而非结构化数据
能容忍错误	个别失败不会导致整个系统无法运行
批处理	各项任务之间无需保留对话状态
训练中包含领域知识	模型已经具备相关背景知识

不适合大模型处理的任务具有以下特征：

特征	不适用原因
精确计算	数学运算、计数和精确算法的结果不可靠
实时要求	大模型的延迟过高，无法满足亚秒级响应
要求绝对准确	存在幻觉风险，因此无法保证 100% 准确
依赖专有数据	模型缺少必要的背景信息
存在顺序依赖	每一步都严重依赖上一步的结果
要求确定性输出	相同输入必须产生完全相同的输出

应通过手动原型测试进行评估：选取一个有代表性的示例，直接使用目标模型进行测试，然后再着手构建自动化流程。

手动原型测试步骤

在投入资源进行自动化之前，先通过手动测试验证任务与模型的匹配度。使用获准的合成或精简输入，在获批的模型界面中进行测试；切勿将专有数据上传到未经批准的服务。评估输出质量。这个过程只需几分钟，却能避免数小时的无效开发。

这项验证可以回答以下关键问题：

• 模型是否具备完成此任务所需的知识？
• 模型能否按所需格式生成输出？
• 扩大规模后，预期能达到怎样的质量？
• 是否存在需要解决的明显失效模式？

原型测试失败是一个用于诊断问题的节点，并不能证明所有架构都会失败。成功的示例只是起点，并不代表已验证规模化能力；应使用留出的评估数据测试有代表性及对抗性案例。

流水线架构

LLM 项目适合采用分阶段的流水线架构，其中每个阶段都应具备以下特点：

• 离散：阶段之间有明确的边界
• 幂等：重复执行操作不会重复产生外部可见的效果；LLM 文本相同则属于另一种确定性属性
• 可缓存：中间结果会持久化到磁盘
• 独立：每个阶段都可以单独运行

规范的流水线结构：

acquire → prepare → process → parse → render

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

采集过程可能随时间变化；只有在输入、版本和设置都固定的情况下，准备、解析和渲染才可能是确定性的。第 3 阶段具有非确定性且开销大。这样的拆分可以只在必要时重新运行开销大的 LLM 阶段，同时快速迭代解析和渲染。

将文件系统用作状态机

使用文件系统跟踪流水线状态，而不是使用数据库或内存结构。为每个处理单元创建一个目录。通过文件是否存在来标记各阶段是否完成。

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

仅凭文件是否存在，无法确定操作已完成或具有幂等性。先写入临时文件，并仅在验证通过后以原子方式重命名；在清单中记录输入哈希、模型／提示词／工具版本、架构、状态、输出哈希和请求标识符。将部分或过期输出视为未完成；在修改每个项目时加锁；依赖项变化时使下游缓存失效。对于不确定是否成功的付费操作或外部操作，不要盲目删除证据后重试：应使用已持久化的请求 ID 进行核对。当并发写入者或事务要求超出基于文件的协调能力时，使用数据库／队列。

结构化输出设计

当 LLM 输出需要通过程序解析时，提示词设计会直接决定解析的可靠性。提示词必须通过示例明确指定格式要求。

有效的结构说明包括：

1. 分节标记：用于解析的显式标题或前缀
2. 格式示例：准确展示输出应有的样子
3. 说明用途：“我将通过程序解析此内容”
4. 受限值：枚举选项、分数范围、格式

提示词结构示例：

Analyze the following and provide your response in exactly this format:

## Summary
[Your summary here]

## Score
Rating: [1-10]

## Details
- Key point 1
- Key point 2

Follow this format exactly because I will be parsing it programmatically.

解析代码必须能妥善处理各种差异。LLM 不会完美遵循指令。构建解析器时应：

• 使用足够灵活的正则表达式模式，以应对细微的格式差异
• 拒绝或标记缺少必填字段的情况；绝不要编造一个看似成功的默认分数
• 记录解析失败，以便后续审查，而不是直接崩溃

Agent 辅助开发

现代具备 Agent 能力的模型可以显著加速开发。常见模式如下：

1. 描述项目目标和约束
2. 让 Agent 生成初始实现
3. 针对具体故障进行测试和迭代
4. 根据结果完善提示词和架构

关键在于快速迭代：生成、测试、修复、重复。Agent 负责处理样板代码和初始结构，你则专注于特定领域的要求和边界情况。

有效开展 Agent 辅助开发的关键实践：

• 提前提供清晰、具体的要求
• 将大型项目拆分为离散的组件
• 每个组件都经过测试后再进入下一个
• 让 Agent 一次专注于一项任务

成本与规模估算

大模型处理的成本具有可预测性，应在开始前进行估算。公式如下：

Total cost = input_tokens × input_rate + output_tokens × output_rate + reasoning/tool/media charges + retries + infrastructure

批量处理时：

• 估算每项的输入 Token 数（提示词 + 上下文）
• 估算每项的输出 Token 数（典型响应长度）
• 乘以项目数量
• 额外预留 20-30% 的缓冲空间，以应对重试和失败

开发过程中跟踪实际成本。如果成本大幅超出估算值，请重新评估方案。可以考虑：

• 通过截断缩短上下文
• 对较简单的项目使用较小的模型
• 缓存并重复使用部分结果
• 并行处理以缩短实际耗时（不会减少 Token 成本）

详细主题

选择单 Agent 还是多 Agent 架构

单 Agent 流水线适用于：

• 对相互独立的项目进行批量处理
• 项目之间互不影响的任务
• 更简单的成本和复杂度管理

多 Agent 架构适用于：

• 并行探索不同方面
• 超出单个上下文窗口容量的任务
• 专业子 Agent 能够提升质量的场景

采用多 Agent 的首要原因是隔离上下文，而不是拟人化角色。子 Agent 会获得全新的上下文窗口来专注处理子任务，从而防止长时间运行的任务中上下文质量下降。

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

架构精简

从最简架构开始。只有在证明确有必要时，才增加复杂性。评估减少工具是否能改善实际任务；更广泛的 Shell/SQL 基础能力可能会扩大权限和故障影响。

链接的 Vercel 案例研究是一个特定环境下的示例，并不能保证普遍提升成功率。

精简优于复杂架构的场景：

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

复杂架构必不可少的场景：

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

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

迭代与重构

做好重构的准备。大规模生产 Agent 系统需要经过多轮架构迭代。链接的上下文工程经验具有历史背景，且仅适用于特定环境。Bitter Lesson 指出，针对当前模型局限而添加的结构，会随着模型进步而成为约束。

为变化而构建：

• 保持架构简单且不预设立场
• 使用不同能力的模型进行测试，以确认你的工具框架不会限制性能
• 设计能从模型改进中获益，而非固守其局限的系统

实践指南

项目规划模板

1. 任务分析

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

2. 手动验证

   • 使用目标模型测试一个示例
   • 评估输出质量和格式
   • 找出失效模式
   • 估算每项的 Token 数

3. 架构选择

   • 单流水线还是多 Agent
   • 所需工具和数据源
   • 存储与缓存策略
   • 并行化方案

4. 成本估算

   • 项目数 × Token 数 × 单价
   • 开发时间
   • 基础设施需求
   • 持续运营成本

5. 开发计划

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

应避免的反模式

跳过手动验证：在确认模型能够完成任务之前就构建自动化流程，如果方法存在根本性缺陷，会浪费大量时间。

单体式流水线：把所有阶段合并到一个脚本中，会增加调试和迭代的难度。应将各阶段分开，并保留持久化的中间输出。

对模型约束过度：只有经过评估后，才能移除冗余的工作流复杂性；确定性的授权、输入／输出验证和安全边界应保留在模型之外。

等到投产后才考虑成本：规模扩大后，Token 成本会迅速累积。从一开始就估算并跟踪成本。

要求完美解析：不要指望 LLM 完美遵循格式说明。应构建能够处理各种变化的健壮解析器。

过早优化：在基础流水线尚未正常运行前，就添加缓存、并行化和优化。

示例

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

任务：结合事后评估，对 10 年前的 930 条 HN 讨论进行分析。

架构：

• 5 阶段流水线：获取 → 提示词 → 分析 → 解析 → 渲染
• 文件系统状态：data/{date}/{item_id}/，其中包含各阶段的输出文件
• 结构化输出：6 个部分，并明确规定格式要求
• 并行执行：15 个工作线程调用 LLM

历史案例研究的结果需要根据链接的主要来源及其评估条件进行验证。它们并非新项目的成本、延迟或成功率估算。本资料不包含案例研究或流水线模式支持文件。

指南

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

集成

此技能与以下内容相关：

• context-fundamentals - 了解提示词设计中的上下文限制
• tool-design - 设计适用于流水线中 Agent 系统的工具
• multi-agent-patterns - 何时使用多 Agent 流程，而非单一流水线
• evaluation - 评估流水线输出和 Agent 性能
• context-compression - 当流水线超出限制时管理上下文

参考资料

内部参考资料：

• Case Studies - Karpathy HN Capsule、Vercel d0、Manus 模式
• Pipeline Patterns - 流水线架构详细指南

本合集中的相关技能：

• 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 上次更新：2025-12-25 作者：Agent Skills for Context Engineering Contributors 版本：1.0.0

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为针对特定环境进行验证、测试或专家审查的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。