project-development
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseProject Development Methodology
项目开发方法论
This skill covers the principles for identifying tasks suited to LLM processing, designing effective project architectures, and iterating rapidly using agent-assisted development. The methodology applies whether building a batch processing pipeline, a multi-agent research system, or an interactive agent application.
本技能涵盖了识别适合LLM处理的任务、设计高效项目架构，以及利用Agent辅助开发快速迭代的原则。无论你是构建批处理管道、多Agent研究系统，还是交互式Agent应用，这套方法论都适用。
When to Activate
适用场景
Activate this skill when:
- Starting a new project that might benefit from LLM processing
- Evaluating whether a task is well-suited for agents versus traditional code
- Designing the architecture for an LLM-powered application
- Planning a batch processing pipeline with structured outputs
- Choosing between single-agent and multi-agent approaches
- Estimating costs and timelines for LLM-heavy projects
在以下场景中激活本技能：
- 启动可能受益于LLM处理的新项目
- 评估某项任务更适合用Agent还是传统代码实现
- 设计基于LLM的应用架构
- 规划带有结构化输出的批处理管道
- 在单Agent与多Agent方案间做选择
- 估算LLM密集型项目的成本与时间线
Core Concepts
核心概念
Task-Model Fit Recognition
任务-模型适配性识别
Not every problem benefits from LLM processing. The first step in any project is evaluating whether the task characteristics align with LLM strengths. This evaluation should happen before writing any code.
LLM-suited tasks share these characteristics:
| Characteristic | Why It Fits |
|---|---|
| Synthesis across sources | LLMs excel at combining information from multiple inputs |
| Subjective judgment with rubrics | LLMs handle grading, evaluation, and classification with criteria |
| Natural language output | When the goal is human-readable text, not structured data |
| Error tolerance | Individual failures do not break the overall system |
| Batch processing | No conversational state required between items |
| Domain knowledge in training | The model already has relevant context |
LLM-unsuited tasks share these characteristics:
| Characteristic | Why It Fails |
|---|---|
| Precise computation | Math, counting, and exact algorithms are unreliable |
| Real-time requirements | LLM latency is too high for sub-second responses |
| Perfect accuracy requirements | Hallucination risk makes 100% accuracy impossible |
| Proprietary data dependence | The model lacks necessary context |
| Sequential dependencies | Each step depends heavily on the previous result |
| Deterministic output requirements | Same input must produce identical output |
The evaluation should happen through manual prototyping: take one representative example and test it directly with the target model before building any automation.
并非所有问题都能从LLM处理中受益。任何项目的第一步都是评估任务特性是否与LLM的优势匹配，这一步应在编写任何代码前完成。
适合LLM的任务具备以下特征：
| 特征 | 适配原因 |
|---|---|
| 跨来源信息合成 | LLMs擅长整合多输入来源的信息 |
| 基于评分标准的主观判断 | LLMs可处理带有评判标准的评分、评估与分类任务 |
| 自然语言输出 | 目标为人类可读文本而非结构化数据时 |
| 容错性 | 单个任务失败不会破坏整个系统 |
| 批处理 | 项目间无需会话状态 |
| 训练数据包含领域知识 | 模型已具备相关上下文 |
不适合LLM的任务具备以下特征：
| 特征 | 不适配原因 |
|---|---|
| 精确计算 | 数学运算、计数与精确算法的结果不可靠 |
| 实时性要求 | LLM的延迟过高，无法提供亚秒级响应 |
| 要求100%准确率 | 幻觉风险导致无法实现完全准确 |
| 依赖专有数据 | 模型缺少必要的上下文信息 |
| 序列依赖 | 每一步都严重依赖前一步的结果 |
| 确定性输出要求 | 相同输入必须产生完全一致的输出 |
评估需通过手动原型验证：在构建任何自动化系统前，选取一个代表性示例直接用目标模型测试。
The Manual Prototype Step
手动原型验证步骤
Before investing in automation, validate task-model fit with a manual test. Copy one representative input into the model interface. Evaluate the output quality. This takes minutes and prevents hours of wasted development.
This validation answers critical questions:
- Does the model have the knowledge required for this task?
- Can the model produce output in the format you need?
- What level of quality should you expect at scale?
- Are there obvious failure modes to address?
If the manual prototype fails, the automated system will fail. If it succeeds, you have a baseline for comparison and a template for prompt design.
在投入自动化开发前，通过手动测试验证任务-模型适配性。将一个代表性输入复制到模型界面，评估输出质量。这一步仅需数分钟，却能避免数小时的无效开发。
该验证可解答关键问题：
- 模型是否具备完成该任务所需的知识？
- 模型能否生成你需要的格式的输出？
- 大规模运行时你能预期何种质量水平？
- 是否存在需要解决的明显失败模式？
如果手动原型验证失败，自动化系统也会失败。如果验证成功，你就有了对比基准和提示词设计模板。
Pipeline Architecture
管道架构
LLM projects benefit from staged pipeline architectures where each stage is:
- Discrete: Clear boundaries between stages
- Idempotent: Re-running produces the same result
- Cacheable: Intermediate results persist to disk
- Independent: Each stage can run separately
The canonical pipeline structure:
acquire → prepare → process → parse → render- Acquire: Fetch raw data from sources (APIs, files, databases)
- Prepare: Transform data into prompt format
- Process: Execute LLM calls (the expensive, non-deterministic step)
- Parse: Extract structured data from LLM outputs
- Render: Generate final outputs (reports, files, visualizations)
Stages 1, 2, 4, and 5 are deterministic. Stage 3 is non-deterministic and expensive. This separation allows re-running the expensive LLM stage only when necessary, while iterating quickly on parsing and rendering.
LLM项目受益于分阶段的管道架构，每个阶段需满足：
- 离散性：各阶段边界清晰
- 幂等性：重复运行可得到相同结果
- 可缓存：中间结果持久化到磁盘
- 独立性：各阶段可单独运行
标准管道结构：
acquire → prepare → process → parse → render- Acquire（获取）：从数据源（API、文件、数据库）提取原始数据
- Prepare（预处理）：将数据转换为提示词格式
- Process（处理）：执行LLM调用（成本高、非确定性步骤）
- Parse（解析）：从LLM输出中提取结构化数据
- Render（渲染）：生成最终输出（报告、文件、可视化内容）
第1、2、4、5阶段是确定性的，第3阶段是非确定性且成本高昂的。这种分离使得仅在必要时重新运行昂贵的LLM阶段，同时可快速迭代解析和渲染环节。
File System as State Machine
以文件系统作为状态机
Use the file system to track pipeline state rather than databases or in-memory structures. Each processing unit gets a directory. Each stage completion is marked by file existence.
data/{id}/
├── raw.json # acquire stage complete
├── prompt.md # prepare stage complete
├── response.md # process stage complete
├── parsed.json # parse stage completeTo check if an item needs processing: check if the output file exists. To re-run a stage: delete its output file and downstream files. To debug: read the intermediate files directly.
This pattern provides:
- Natural idempotency (file existence gates execution)
- Easy debugging (all state is human-readable)
- Simple parallelization (each directory is independent)
- Trivial caching (files persist across runs)
使用文件系统而非数据库或内存结构来跟踪管道状态。每个处理单元对应一个目录，每个阶段完成后会生成对应文件来标记状态。
data/{id}/
├── raw.json # 获取阶段完成
├── prompt.md # 预处理阶段完成
├── response.md # 处理阶段完成
├── parsed.json # 解析阶段完成检查某个项目是否需要处理：查看输出文件是否存在。重新运行某个阶段：删除该阶段的输出文件及下游文件。调试：直接读取中间文件。
这种模式的优势：
- 天然具备幂等性（文件存在与否控制执行）
- 调试便捷（所有状态都是人类可读的）
- 易于并行化（每个目录相互独立）
- 缓存简单（文件可跨运行周期持久化）
Structured Output Design
结构化输出设计
When LLM outputs must be parsed programmatically, prompt design directly determines parsing reliability. The prompt must specify exact format requirements with examples.
Effective structure specification includes:
- Section markers: Explicit headers or prefixes for parsing
- Format examples: Show exactly what output should look like
- Rationale disclosure: "I will be parsing this programmatically"
- Constrained values: Enumerated options, score ranges, formats
Example prompt structure:
Analyze the following and provide your response in exactly this format:当LLM输出需要被程序化解析时，提示词设计直接决定了解析的可靠性。提示词必须明确指定精确的格式要求并提供示例。
有效的结构规范包括：
- 分段标记：用于解析的明确标题或前缀
- 格式示例：展示输出应有的精确样式
- 说明解析需求："我将对该输出进行程序化解析"
- 值约束：枚举选项、评分范围、格式要求
示例提示词结构：
分析以下内容并严格按照此格式提供响应：Summary
摘要
[Your summary here]
[在此处填写你的摘要]
Score
评分
Rating: [1-10]
评分: [1-10]
Details
详情
- Key point 1
- Key point 2
Follow this format exactly because I will be parsing it programmatically.
The parsing code must handle variations gracefully. LLMs do not follow instructions perfectly. Build parsers that:
- Use regex patterns flexible enough to handle minor formatting variations
- Provide sensible defaults when sections are missing
- Log parsing failures for later review rather than crashing- 关键点1
- 关键点2
请严格遵循此格式，因为我将对该输出进行程序化解析。
解析代码必须能灵活处理格式变化。LLM无法完美遵循指令，需构建具备以下特性的解析器：
- 使用足够灵活的正则表达式处理轻微格式变化
- 当某些部分缺失时提供合理默认值
- 记录解析失败以便后续审查，而非直接崩溃Agent-Assisted Development
Agent辅助开发
Modern agent-capable models can accelerate development significantly. The pattern is:
- Describe the project goal and constraints
- Let the agent generate initial implementation
- Test and iterate on specific failures
- Refine prompts and architecture based on results
This is about rapid iteration: generate, test, fix, repeat. The agent handles boilerplate and initial structure while you focus on domain-specific requirements and edge cases.
Key practices for effective agent-assisted development:
- Provide clear, specific requirements upfront
- Break large projects into discrete components
- Test each component before moving to the next
- Keep the agent focused on one task at a time
具备Agent能力的现代模型可显著加速开发流程，模式如下：
- 描述项目目标与约束条件
- 让Agent生成初始实现代码
- 测试并针对特定失败点迭代优化
- 根据结果优化提示词与架构
核心在于快速迭代：生成、测试、修复、重复。Agent处理样板代码和初始结构，你则专注于领域特定需求和边缘案例。
有效Agent辅助开发的关键实践：
- 提前提供清晰、具体的需求
- 将大型项目拆分为离散组件
- 在进入下一环节前测试每个组件
- 让Agent一次专注于一项任务
Cost and Scale Estimation
成本与规模估算
LLM processing has predictable costs that should be estimated before starting. The formula:
Total cost = (items × tokens_per_item × price_per_token) + API overheadFor batch processing:
- Estimate input tokens per item (prompt + context)
- Estimate output tokens per item (typical response length)
- Multiply by item count
- Add 20-30% buffer for retries and failures
Track actual costs during development. If costs exceed estimates significantly, re-evaluate the approach. Consider:
- Reducing context length through truncation
- Using smaller models for simpler items
- Caching and reusing partial results
- Parallel processing to reduce wall-clock time (not token cost)
LLM处理的成本可预测，应在项目启动前估算。计算公式：
总成本 = (项目数量 × 每个项目的令牌数 × 每令牌价格) + API开销对于批处理：
- 估算每个项目的输入令牌数（提示词+上下文）
- 估算每个项目的输出令牌数（典型响应长度）
- 乘以项目数量
- 增加20-30%的缓冲，用于重试和失败处理
在开发过程中跟踪实际成本。如果成本远超估算，需重新评估方案，可考虑：
- 通过截断减少上下文长度
- 对简单任务使用更小的模型
- 缓存并复用部分结果
- 并行处理以减少耗时（不减少令牌成本）
Detailed Topics
详细主题
Choosing Single vs Multi-Agent Architecture
选择单Agent vs 多Agent架构
Single-agent pipelines work for:
- Batch processing with independent items
- Tasks where items do not interact
- Simpler cost and complexity management
Multi-agent architectures work for:
- Parallel exploration of different aspects
- Tasks exceeding single context window capacity
- When specialized sub-agents improve quality
The primary reason for multi-agent is context isolation, not role anthropomorphization. Sub-agents get fresh context windows for focused subtasks. This prevents context degradation on long-running tasks.
See skill for detailed architecture guidance.
multi-agent-patterns单Agent管道适用于：
- 处理相互独立的批处理项目
- 项目间无需交互的任务
- 成本与复杂度管理更简单的场景
多Agent架构适用于：
- 并行探索不同方面的任务
- 超出单个上下文窗口容量的任务
- 专业子Agent可提升质量的场景
使用多Agent的主要原因是上下文隔离，而非角色拟人化。子Agent可获得全新的上下文窗口来专注于子任务，避免长时任务中的上下文退化。
详见技能中的详细架构指南。
multi-agent-patternsArchitectural Reduction
架构简化
Start with minimal architecture. Add complexity only when proven necessary. Production evidence shows that removing specialized tools often improves performance.
Vercel's d0 agent achieved 100% success rate (up from 80%) by reducing from 17 specialized tools to 2 primitives: bash command execution and SQL. The file system agent pattern uses standard Unix utilities (grep, cat, find, ls) instead of custom exploration tools.
When reduction outperforms complexity:
- Your data layer is well-documented and consistently structured
- The model has sufficient reasoning capability
- Your specialized tools were constraining rather than enabling
- You are spending more time maintaining scaffolding than improving outcomes
When complexity is necessary:
- Your underlying data is messy, inconsistent, or poorly documented
- The domain requires specialized knowledge the model lacks
- Safety constraints require limiting agent capabilities
- Operations are truly complex and benefit from structured workflows
See skill for detailed tool architecture guidance.
tool-design从最简架构开始，仅在证明必要时增加复杂度。生产实践表明，移除专用工具往往能提升性能。
Vercel的d0 Agent通过将17个专用工具简化为2个基础工具（bash命令执行和SQL），成功率从80%提升至100%。文件系统Agent模式使用标准Unix工具（grep、cat、find、ls）而非自定义探索工具。
简化优于复杂化的场景：
- 你的数据层文档完善且结构一致
- 模型具备足够的推理能力
- 你的专用工具起到了约束而非赋能作用
- 你在维护架构上花费的时间多于优化结果的时间
需要复杂化的场景：
- 底层数据杂乱、不一致或文档缺失
- 领域需要模型不具备的专业知识
- 安全约束需要限制Agent能力
- 操作确实复杂，可从结构化工作流中受益
详见技能中的详细工具架构指南。
tool-designIteration and Refactoring
迭代与重构
Expect to refactor. Production agent systems at scale require multiple architectural iterations. Manus refactored their agent framework five times since launch. The Bitter Lesson suggests that structures added for current model limitations become constraints as models improve.
Build for change:
- Keep architecture simple and unopinionated
- Test across model strengths to verify your harness is not limiting performance
- Design systems that benefit from model improvements rather than locking in limitations
要做好重构的准备。大规模生产级Agent系统需要多次架构迭代。Manus自上线以来已重构其Agent框架五次。“痛苦教训”表明，为当前模型局限性添加的结构会随着模型能力提升而成为约束。
为变化而构建：
- 保持架构简单且无偏见
- 跨模型能力测试，验证你的框架是否限制了性能
- 设计可从模型能力提升中获益的系统，而非固化局限性
Practical Guidance
实践指南
Project Planning Template
项目规划模板
-
Task Analysis
- What is the input? What is the desired output?
- Is this synthesis, generation, classification, or analysis?
- What error rate is acceptable?
- What is the value per successful completion?
-
Manual Validation
- Test one example with target model
- Evaluate output quality and format
- Identify failure modes
- Estimate tokens per item
-
Architecture Selection
- Single pipeline vs multi-agent
- Required tools and data sources
- Storage and caching strategy
- Parallelization approach
-
Cost Estimation
- Items × tokens × price
- Development time
- Infrastructure requirements
- Ongoing operational costs
-
Development Plan
- Stage-by-stage implementation
- Testing strategy per stage
- Iteration milestones
- Deployment approach
-
任务分析
- 输入是什么？期望输出是什么？
- 这是合成、生成、分类还是分析任务？
- 可接受的错误率是多少？
- 每次成功完成的价值是什么？
-
手动验证
- 用目标模型测试一个示例
- 评估输出质量与格式
- 识别失败模式
- 估算每个项目的令牌数
-
架构选择
- 单管道 vs 多Agent
- 所需工具与数据源
- 存储与缓存策略
- 并行化方案
-
成本估算
- 项目数量 × 令牌数 × 价格
- 开发时间
- 基础设施需求
- 持续运营成本
-
开发计划
- 分阶段实施
- 各阶段测试策略
- 迭代里程碑
- 部署方案
Anti-Patterns to Avoid
需避免的反模式
Skipping manual validation: Building automation before verifying the model can do the task wastes significant time when the approach is fundamentally flawed.
Monolithic pipelines: Combining all stages into one script makes debugging and iteration difficult. Separate stages with persistent intermediate outputs.
Over-constraining the model: Adding guardrails, pre-filtering, and validation logic that the model could handle on its own. Test whether your scaffolding helps or hurts.
Ignoring costs until production: Token costs compound quickly at scale. Estimate and track from the beginning.
Perfect parsing requirements: Expecting LLMs to follow format instructions perfectly. Build robust parsers that handle variations.
Premature optimization: Adding caching, parallelization, and optimization before the basic pipeline works correctly.
跳过手动验证：在验证模型能否完成任务前就构建自动化系统，当方案存在根本性缺陷时会浪费大量时间。
单体管道：将所有阶段合并到一个脚本中会导致调试和迭代困难。应将各阶段分离并保留持久化的中间输出。
过度约束模型：添加模型自身可处理的防护、预过滤和验证逻辑。测试你的架构是起到了帮助还是阻碍作用。
直到生产阶段才考虑成本：令牌成本在规模扩大时会迅速累积。从项目开始就估算并跟踪成本。
要求完美解析：期望LLM完全遵循格式指令。需构建能处理格式变化的健壮解析器。
过早优化：在基础管道正常工作前就添加缓存、并行化和优化措施。
Examples
示例
Example 1: Batch Analysis Pipeline (Karpathy's HN Time Capsule)
Task: Analyze 930 HN discussions from 10 years ago with hindsight grading.
Architecture:
- 5-stage pipeline: fetch → prompt → analyze → parse → render
- File system state: data/{date}/{item_id}/ with stage output files
- Structured output: 6 sections with explicit format requirements
- Parallel execution: 15 workers for LLM calls
Results: $58 total cost, ~1 hour execution, static HTML output.
Example 2: Architectural Reduction (Vercel d0)
Task: Text-to-SQL agent for internal analytics.
Before: 17 specialized tools, 80% success rate, 274s average execution.
After: 2 tools (bash + SQL), 100% success rate, 77s average execution.
Key insight: The semantic layer was already good documentation. Claude just needed access to read files directly.
See Case Studies for detailed analysis.
示例1：批处理分析管道（Karpathy的HN时间胶囊）
任务：以事后视角分析10年前的930条HN讨论内容。
架构：
- 5阶段管道：获取 → 提示词生成 → 分析 → 解析 → 渲染
- 文件系统状态：data/{date}/{item_id}/ 包含各阶段输出文件
- 结构化输出：6个部分，带有明确格式要求
- 并行执行：15个Worker处理LLM调用
结果：总成本58美元，执行时间约1小时，输出静态HTML内容。
示例2：架构简化（Vercel d0）
任务：用于内部分析的文本转SQL Agent。
优化前：17个专用工具，成功率80%，平均执行时间274秒。
优化后：2个工具（bash + SQL），成功率100%，平均执行时间77秒。
关键洞察：语义层已有完善的文档，Claude只需直接读取文件即可。
详见案例研究获取详细分析。
Guidelines
指南
- Validate task-model fit with manual prototyping before building automation
- Structure pipelines as discrete, idempotent, cacheable stages
- Use the file system for state management and debugging
- Design prompts for structured, parseable outputs with explicit format examples
- Start with minimal architecture; add complexity only when proven necessary
- Estimate costs early and track throughout development
- Build robust parsers that handle LLM output variations
- Expect and plan for multiple architectural iterations
- Test whether scaffolding helps or constrains model performance
- Use agent-assisted development for rapid iteration on implementation
- 在构建自动化系统前，通过手动原型验证任务-模型适配性
- 将管道结构设计为离散、幂等、可缓存的阶段
- 使用文件系统进行状态管理与调试
- 设计提示词以生成结构化、可解析的输出，并提供明确格式示例
- 从最简架构开始，仅在证明必要时增加复杂度
- 尽早估算成本并在开发全程跟踪
- 构建能处理LLM输出格式变化的健壮解析器
- 预期并规划多次架构迭代
- 测试架构是帮助还是约束了模型性能
- 利用Agent辅助开发实现快速迭代
Integration
集成
This skill connects to:
- context-fundamentals - Understanding context constraints for prompt design
- tool-design - Designing tools for agent systems within pipelines
- multi-agent-patterns - When to use multi-agent versus single pipelines
- evaluation - Evaluating pipeline outputs and agent performance
- context-compression - Managing context when pipelines exceed limits
本技能与以下内容相关：
- context-fundamentals - 理解提示词设计的上下文约束
- tool-design - 在管道中为Agent系统设计工具
- multi-agent-patterns - 何时使用多Agent而非单管道
- evaluation - 评估管道输出与Agent性能
- context-compression - 当管道超出上下文限制时的上下文管理
References
参考资料
Internal references:
- Case Studies - Karpathy HN Capsule, Vercel d0, Manus patterns
- Pipeline Patterns - Detailed pipeline architecture guidance
Related skills in this collection:
- tool-design - Tool architecture and reduction patterns
- multi-agent-patterns - When to use multi-agent architectures
- evaluation - Output evaluation frameworks
External resources:
- Karpathy's HN Time Capsule project: https://github.com/karpathy/hn-time-capsule
- Vercel d0 architectural reduction: https://vercel.com/blog/we-removed-80-percent-of-our-agents-tools
- Manus context engineering: Peak Ji's blog on context engineering lessons
- Anthropic multi-agent research: How we built our multi-agent research system
内部参考：
- 案例研究 - Karpathy HN时间胶囊、Vercel d0、Manus模式
- 管道模式 - 详细的管道架构指南
本集合中的相关技能：
- tool-design - 工具架构与简化模式
- multi-agent-patterns - 何时使用多Agent架构
- 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多Agent研究：我们如何构建多Agent研究系统
Skill Metadata
技能元数据
Created: 2025-12-25
Last Updated: 2025-12-25
Author: Agent Skills for Context Engineering Contributors
Version: 1.0.0
创建时间: 2025-12-25
最后更新时间: 2025-12-25
作者: Agent Skills for Context Engineering Contributors
版本: 1.0.0