# Project Development

> 本技能涵盖识别适合 LLM 处理的任务、设计高效项目架构以及借助智能体辅助开发快速迭代的原则。触发词：项目开发、LLM项目、流水线架构、智能体开发、任务适配、成本估算、批处理流水线

- Skill: `kscz0000/project-development` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kscz0000/project-development`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/project-development/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: kscz0000 (https://skillmd.com/u/kscz0000)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/kscz0000/project-development

---


# 项目开发方法论

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

## 何时使用

在以下场景激活本技能：
- 启动可能受益于 LLM 处理的新项目
- 评估某任务适合用智能体还是传统代码实现
- 设计 LLM 驱动应用的架构
- 规划带结构化输出的批处理流水线
- 在单智能体和多智能体方案之间做选择
- 估算 LLM 密集型项目的成本和工期

## 核心概念

### 任务-模型适配识别

并非所有问题都适合用 LLM 处理。任何项目的首要步骤都是评估任务特征是否与 LLM 的优势匹配。这项评估应在编写任何代码之前完成。

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

| 特征 | 适配原因 |
|------|----------|
| 跨源综合 | LLM 擅长整合来自多个输入的信息 |
| 带评分标准的主观判断 | LLM 能按标准进行评分、评估和分类 |
| 自然语言输出 | 目标是人类可读文本，而非结构化数据 |
| 容错性 | 单个失败不会破坏整体系统 |
| 批处理 | 各条目之间无需对话状态 |
| 训练数据中的领域知识 | 模型已具备相关上下文 |

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

| 特征 | 失败原因 |
|------|----------|
| 精确计算 | 数学、计数和精确算法不可靠 |
| 实时要求 | LLM 延迟过高，无法实现亚秒级响应 |
| 完美精度要求 | 幻觉风险使 100% 准确率不可能实现 |
| 依赖专有数据 | 模型缺乏必要的上下文 |
| 顺序依赖 | 每一步都严重依赖上一步的结果 |
| 确定性输出要求 | 相同输入必须产生完全相同的输出 |

评估应通过手动原型验证完成：取一个代表性示例，在构建任何自动化之前直接用目标模型测试。

### 手动原型验证步骤

在投入自动化之前，通过手动测试验证任务-模型适配性。将一个代表性输入复制到模型界面中，评估输出质量。这只需几分钟，却能避免数小时的无效开发。

此验证能回答以下关键问题：
- 模型是否具备完成此任务所需的知识？
- 模型能否按你需要的格式输出？
- 大规模运行时应预期什么质量水平？
- 是否存在需要解决的明显失败模式？

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

### 流水线架构

LLM 项目受益于分阶段的流水线架构，每个阶段具备：
- **离散性**：阶段之间有清晰边界
- **幂等性**：重新运行产生相同结果
- **可缓存性**：中间结果持久化到磁盘
- **独立性**：每个阶段可单独运行

**标准流水线结构：**

```
acquire → prepare → process → parse → render
```

1. **Acquire**：从数据源获取原始数据（API、文件、数据库）
2. **Prepare**：将数据转换为提示词格式
3. **Process**：执行 LLM 调用（昂贵且非确定性的步骤）
4. **Parse**：从 LLM 输出中提取结构化数据
5. **Render**：生成最终输出（报告、文件、可视化）

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

### 文件系统作为状态机

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

```
data/{id}/
├── raw.json         # acquire 阶段完成
├── prompt.md        # prepare 阶段完成
├── response.md      # process 阶段完成
├── parsed.json      # parse 阶段完成
```

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

此模式提供：
- 天然幂等性（文件存在与否控制执行）
- 便捷调试（所有状态人类可读）
- 简单并行化（各目录相互独立）
- 轻松缓存（文件跨次运行持久化）

### 结构化输出设计

当 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 不会完美遵循指令。构建的解析器应：
- 使用足够灵活的正则表达式模式来处理轻微格式变化
- 在段落缺失时提供合理的默认值
- 记录解析失败以供后续审查，而不是直接崩溃

### 智能体辅助开发

现代具备智能体能力的模型可以显著加速开发。其模式为：

1. 描述项目目标和约束
2. 让智能体生成初始实现
3. 针对具体失败进行测试和迭代
4. 根据结果优化提示词和架构

核心在于快速迭代：生成、测试、修复、重复。智能体负责样板代码和初始结构，你专注于领域特定需求和边界情况。

高效智能体辅助开发的关键实践：
- 提前提供清晰、具体的需求
- 将大项目拆分为独立组件
- 在进入下一个之前先测试每个组件
- 让智能体一次只专注于一个任务

### 成本与规模估算

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 自上线以来已重构其智能体框架五次。"惨痛教训"表明，为当前模型限制而添加的结构，会随着模型改进变成约束。

为变化而构建：
- 保持架构简洁且不预设立场
- 跨模型能力测试以验证你的框架未限制性能
- 设计能从模型改进中受益的系统，而非锁定当前限制

## 实践指导

### 项目规划模板

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

2. **手动验证**
   - 用目标模型测试一个示例
   - 评估输出质量和格式
   - 识别失败模式
   - 估算每条目的 token 数

3. **架构选择**
   - 单流水线 vs 多智能体
   - 所需工具和数据源
   - 存储和缓存策略
   - 并行化方案

4. **成本估算**
   - 条目数 × token 数 × 单价
   - 开发时间
   - 基础设施需求
   - 持续运营成本

5. **开发计划**
   - 分阶段实施
   - 每阶段的测试策略
   - 迭代里程碑
   - 部署方案

### 需要避免的反模式

**跳过手动验证**：在验证模型能完成任务之前就构建自动化，当方案存在根本缺陷时会浪费大量时间。

**单体流水线**：将所有阶段合并到一个脚本中，会使调试和迭代变得困难。应将阶段分离，使用持久化的中间输出。

**过度约束模型**：添加模型本身就能处理的防护栏、预过滤和验证逻辑。测试你的脚手架是在帮助还是在阻碍。

**忽略成本直到上线**：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 只需要直接读取文件的权限。

详见案例研究获取详细分析。

## 准则

1. 在构建自动化之前，通过手动原型验证任务-模型适配性
2. 将流水线构建为离散、幂等、可缓存的阶段
3. 使用文件系统进行状态管理和调试
4. 设计带显式格式示例的结构化、可解析输出的提示词
5. 从最小架构开始，仅在证明确有必要时才增加复杂度
6. 提前估算成本并在整个开发过程中跟踪
7. 构建能处理 LLM 输出变体的健壮解析器
8. 预期并规划多次架构迭代
9. 测试脚手架是在帮助还是限制模型性能
10. 使用智能体辅助开发进行实现的快速迭代

## 集成

本技能连接：
- 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

## 局限性
- 仅在任务明确匹配上述范围时使用本技能。
- 不要将输出视为环境特定验证、测试或专家评审的替代品。
- 如果缺少所需输入、权限、安全边界或成功标准，请停下来寻求澄清。