kscz0000 项目开发方法论
本技能涵盖识别适合 LLM 处理的任务、设计高效项目架构以及借助智能体辅助开发快速迭代的原则。无论是构建批处理流水线、多智能体研究系统还是交互式智能体应用，这套方法论都适用。
何时使用
在以下场景激活本技能：
- 启动可能受益于 LLM 处理的新项目
- 评估某任务适合用智能体还是传统代码实现
- 设计 LLM 驱动应用的架构
- 规划带结构化输出的批处理流水线
- 在单智能体和多智能体方案之间做选择
- 估算 LLM 密集型项目的成本和工期
核心概念
任务-模型适配识别
并非所有问题都适合用 LLM 处理。任何项目的首要步骤都是评估任务特征是否与 LLM 的优势匹配。这项评估应在编写任何代码之前完成。
适合 LLM 的任务具有以下特征：
| 特征 | 适配原因 |
|---|---|
| 跨源综合 | LLM 擅长整合来自多个输入的信息 |
| 带评分标准的主观判断 | LLM 能按标准进行评分、评估和分类 |
| 自然语言输出 | 目标是人类可读文本，而非结构化数据 |
| 容错性 | 单个失败不会破坏整体系统 |
| 批处理 | 各条目之间无需对话状态 |
| 训练数据中的领域知识 | 模型已具备相关上下文 |
不适合 LLM 的任务具有以下特征：
| 特征 | 失败原因 |
|---|---|
| 精确计算 | 数学、计数和精确算法不可靠 |
| 实时要求 | LLM 延迟过高，无法实现亚秒级响应 |
| 完美精度要求 | 幻觉风险使 100% 准确率不可能实现 |
| 依赖专有数据 | 模型缺乏必要的上下文 |
| 顺序依赖 | 每一步都严重依赖上一步的结果 |
| 确定性输出要求 | 相同输入必须产生完全相同的输出 |
评估应通过手动原型验证完成：取一个代表性示例，在构建任何自动化之前直接用目标模型测试。
手动原型验证步骤
在投入自动化之前，通过手动测试验证任务-模型适配性。将一个代表性输入复制到模型界面中，评估输出质量。这只需几分钟，却能避免数小时的无效开发。
此验证能回答以下关键问题：
- 模型是否具备完成此任务所需的知识？
- 模型能否按你需要的格式输出？
- 大规模运行时应预期什么质量水平？
- 是否存在需要解决的明显失败模式？
如果手动原型失败，自动化系统也会失败。如果成功，你就有了比较基线和提示词设计模板。
流水线架构
LLM 项目受益于分阶段的流水线架构，每个阶段具备：
- 离散性：阶段之间有清晰边界
- 幂等性：重新运行产生相同结果
- 可缓存性：中间结果持久化到磁盘
- 独立性：每个阶段可单独运行
标准流水线结构：
acquire → prepare → process → parse → render
- Acquire：从数据源获取原始数据（API、文件、数据库）
- Prepare：将数据转换为提示词格式
- Process：执行 LLM 调用（昂贵且非确定性的步骤）
- Parse：从 LLM 输出中提取结构化数据
- Render：生成最终输出（报告、文件、可视化）
第 1、2、4、5 阶段是确定性的。第 3 阶段是非确定性且昂贵的。这种分离使得仅在必要时才重新运行昂贵的 LLM 阶段，同时在解析和渲染上快速迭代。
文件系统作为状态机
使用文件系统跟踪流水线状态，而非数据库或内存结构。每个处理单元分配一个目录，每个阶段的完成通过文件是否存在来标记。
data/{id}/
├── raw.json # acquire 阶段完成
├── prompt.md # prepare 阶段完成
├── response.md # process 阶段完成
├── parsed.json # parse 阶段完成
检查某条目是否需要处理：检查输出文件是否存在。重新运行某阶段：删除其输出文件及下游文件。调试：直接读取中间文件。
此模式提供：
- 天然幂等性（文件存在与否控制执行）
- 便捷调试（所有状态人类可读）
- 简单并行化（各目录相互独立）
- 轻松缓存（文件跨次运行持久化）
结构化输出设计
当 LLM 输出需要程序化解析时，提示词设计直接决定了解析的可靠性。提示词必须指定精确的格式要求并附带示例。
有效的结构化规范包括：
- 段落标记：用于解析的显式标题或前缀
- 格式示例：精确展示输出应呈现的样子
- 意图说明："我将对此进行程序化解析"
- 约束值：枚举选项、分值范围、格式要求
提示词结构示例：
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 不会完美遵循指令。构建的解析器应：
- 使用足够灵活的正则表达式模式来处理轻微格式变化
- 在段落缺失时提供合理的默认值
- 记录解析失败以供后续审查，而不是直接崩溃
智能体辅助开发
现代具备智能体能力的模型可以显著加速开发。其模式为：
- 描述项目目标和约束
- 让智能体生成初始实现
- 针对具体失败进行测试和迭代
- 根据结果优化提示词和架构
核心在于快速迭代：生成、测试、修复、重复。智能体负责样板代码和初始结构，你专注于领域特定需求和边界情况。
高效智能体辅助开发的关键实践：
- 提前提供清晰、具体的需求
- 将大项目拆分为独立组件
- 在进入下一个之前先测试每个组件
- 让智能体一次只专注于一个任务
成本与规模估算
LLM 处理的成本是可预测的，应在开始前进行估算。公式：
Total cost = (items × tokens_per_item × price_per_token) + API overhead
批处理估算：
- 估算每条目的输入 token 数（提示词 + 上下文）
- 估算每条目的输出 token 数（典型响应长度）
- 乘以条目数量
- 加 20-30% 的重试和失败缓冲
开发过程中跟踪实际成本。如果成本显著超出预期，重新评估方案。考虑：
- 通过截断减少上下文长度
- 对简单条目使用较小的模型
- 缓存和复用部分结果
- 并行处理以减少实际耗时（而非 token 成本）
详细主题
单智能体 vs 多智能体架构选择
单智能体流水线适用于：
- 条目独立的批处理
- 条目之间无交互的任务
- 更简单的成本和复杂度管理
多智能体架构适用于：
- 并行探索不同方面
- 超出单个上下文窗口容量的任务
- 专业化子智能体能提升质量的场景
采用多智能体的首要原因是上下文隔离，而非角色拟人化。子智能体获得全新的上下文窗口来处理聚焦的子任务，这可以防止长时间运行任务中的上下文退化。
详见 multi-agent-patterns 技能获取详细架构指导。
架构精简
从最小架构开始，仅在证明确有必要时才增加复杂度。生产经验证明，移除专业化工具往往能提升性能。
Vercel 的 d0 智能体通过将 17 个专业化工具精简为 2 个原语（bash 命令执行和 SQL），成功率从 80% 提升到 100%。文件系统智能体模式使用标准 Unix 工具（grep、cat、find、ls）替代自定义探索工具。
精简优于复杂的情况：
- 数据层文档完善且结构一致
- 模型具备足够的推理能力
- 专业化工具在限制而非赋能
- 维护脚手架的时间超过改善结果的时间
复杂度必要的场景：
- 底层数据混乱、不一致或文档缺失
- 领域需要模型缺乏的专业知识
- 安全约束要求限制智能体能力
- 操作确实复杂，受益于结构化工作流
详见 tool-design 技能获取详细工具架构指导。
迭代与重构
做好重构准备。生产级智能体系统在规模化时需要多次架构迭代。Manus 自上线以来已重构其智能体框架五次。"惨痛教训"表明，为当前模型限制而添加的结构，会随着模型改进变成约束。
为变化而构建：
- 保持架构简洁且不预设立场
- 跨模型能力测试以验证你的框架未限制性能
- 设计能从模型改进中受益的系统，而非锁定当前限制
实践指导
项目规划模板
任务分析
- 输入是什么？期望输出是什么？
- 这是综合、生成、分类还是分析？
- 可接受的错误率是多少？
- 每次成功完成的价值是多少？
手动验证
- 用目标模型测试一个示例
- 评估输出质量和格式
- 识别失败模式
- 估算每条目的 token 数
架构选择
- 单流水线 vs 多智能体
- 所需工具和数据源
- 存储和缓存策略
- 并行化方案
成本估算
- 条目数 × token 数 × 单价
- 开发时间
- 基础设施需求
- 持续运营成本
开发计划
- 分阶段实施
- 每阶段的测试策略
- 迭代里程碑
- 部署方案
需要避免的反模式
跳过手动验证：在验证模型能完成任务之前就构建自动化，当方案存在根本缺陷时会浪费大量时间。
单体流水线：将所有阶段合并到一个脚本中，会使调试和迭代变得困难。应将阶段分离，使用持久化的中间输出。
过度约束模型：添加模型本身就能处理的防护栏、预过滤和验证逻辑。测试你的脚手架是在帮助还是在阻碍。
忽略成本直到上线：token 成本在规模化时会快速累积。从一开始就估算和跟踪。
要求完美解析：期望 LLM 完美遵循格式指令。应构建能处理变体的健壮解析器。
过早优化：在基础流水线正确运行之前就添加缓存、并行化和优化。
示例
示例 1：批处理分析流水线（Karpathy 的 HN 时间胶囊）
任务：分析 930 条 10 年前的 HN 讨论，进行事后评分。
架构：
- 5 阶段流水线：fetch → prompt → analyze → parse → render
- 文件系统状态：data/{date}/{item_id}/ 包含各阶段输出文件
- 结构化输出：6 个段落，带显式格式要求
- 并行执行：15 个 worker 处理 LLM 调用
结果：总成本 $58，约 1 小时执行，静态 HTML 输出。
示例 2：架构精简（Vercel d0）
任务：用于内部分析的 Text-to-SQL 智能体。
精简前：17 个专业化工具，80% 成功率，平均执行 274 秒。
精简后：2 个工具（bash + SQL），100% 成功率，平均执行 77 秒。
关键洞察：语义层已经是很好的文档。Claude 只需要直接读取文件的权限。
详见案例研究获取详细分析。
准则
- 在构建自动化之前，通过手动原型验证任务-模型适配性
- 将流水线构建为离散、幂等、可缓存的阶段
- 使用文件系统进行状态管理和调试
- 设计带显式格式示例的结构化、可解析输出的提示词
- 从最小架构开始，仅在证明确有必要时才增加复杂度
- 提前估算成本并在整个开发过程中跟踪
- 构建能处理 LLM 输出变体的健壮解析器
- 预期并规划多次架构迭代
- 测试脚手架是在帮助还是限制模型性能
- 使用智能体辅助开发进行实现的快速迭代
集成
本技能连接：
- context-fundamentals - 理解提示词设计的上下文约束
- tool-design - 在流水线中设计智能体系统的工具
- multi-agent-pattern - 何时使用多智能体而非单流水线
- evaluation - 评估流水线输出和智能体性能
- context-compression - 当流水线超出限制时管理上下文
参考资料
内部参考：
- Case Studies - Karpathy HN Capsule、Vercel d0、Manus 模式
- Pipeline Patterns - 详细的流水线架构指导
本系列相关技能：
- tool-design - 工具架构与精简模式
- multi-agent-patterns - 何时使用多智能体架构
- 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 多智能体研究：我们如何构建多智能体研究系统
技能元数据
创建日期：2025-12-25 最后更新：2025-12-25 作者：Agent Skills for Context Engineering Contributors 版本：1.0.0
局限性
- 仅在任务明确匹配上述范围时使用本技能。
- 不要将输出视为环境特定验证、测试或专家评审的替代品。
- 如果缺少所需输入、权限、安全边界或成功标准，请停下来寻求澄清。