project-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Project 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.
The unit of work for this skill is the whole project or a multi-stage pipeline. Individual tool design (descriptions, schemas, error messages) belongs to
tool-design
. Per-skill activation routing belongs to the corresponding skill plus the corpus index. This skill owns the project-level questions: should you build this with an LLM at all, what shape should the pipeline take, what does it cost, how should it be iterated.
本 Skill 介绍如何识别适合 LLM 处理的任务、设计有效的项目架构,以及使用 Agent 辅助开发进行快速迭代的原则。无论构建的是批处理流水线、多 Agent 研究系统,还是交互式 Agent 应用,该方法论都适用。
本 Skill 的工作单元是完整项目或多阶段流水线。单工具设计(描述、schema、错误消息)属于
tool-design
。单个 Skill 的激活路由属于相应的 Skill 和语料库索引。本 Skill 负责项目级问题:是否应该使用 LLM 构建、流水线应采用什么结构、成本是多少,以及应如何迭代。

When to Activate

何时激活

Activate this skill when the unit of work is a whole project or pipeline:
  • Deciding whether an LLM is the right primitive for a task at all (task-model fit before any code).
  • Shaping a multi-stage batch or agent pipeline (acquire / prepare / process / parse / render).
  • Estimating tokens, dollar cost, and timelines for an LLM-heavy project.
  • Choosing between single-agent and multi-agent at the project level.
  • Structuring agent-assisted iteration (where the agent helps build the project itself).
  • Designing structured output at the pipeline contract level (cross-stage handoff format).
Do not activate this skill for adjacent work owned by other skills:
  • Per-tool description, schema, naming, response format, error message:
    tool-design
    .
  • Per-trajectory token-efficiency tactics (masking, partitioning, caching):
    context-optimization
    .
  • Deciding to split work across sub-agents at the agent topology level:
    multi-agent-patterns
    .
  • Designing the autonomous control loop (locked metrics, novelty gates, human approval boundaries):
    harness-engineering
    .
当工作单元是完整项目或流水线时激活本 Skill:
  • 在编写任何代码之前,判断 LLM 是否适合该任务(先评估任务与模型的匹配度)。
  • 设计多阶段批处理或 Agent 流水线的结构(获取 / 准备 / 处理 / 解析 / 渲染)。
  • 估算 LLM 密集型项目的 token、美元成本和交付周期。
  • 在项目层面选择单 Agent 或多 Agent 架构。
  • 组织 Agent 辅助迭代(由 Agent 协助构建项目本身)。
  • 在流水线契约层面设计结构化输出(跨阶段交接格式)。
不要为以下相邻工作激活本 Skill:
  • 单个工具的描述、schema、命名、响应格式和错误消息:
    tool-design
    。
  • 单条轨迹的 token 效率策略(掩码、分区、缓存):
    context-optimization
    。
  • 在 Agent 拓扑层面决定是否将工作拆分给子 Agent:
    multi-agent-patterns
    。
  • 设计自主控制循环(锁定指标、新颖性门控、人类审批边界):
    harness-engineering
    。

Core Concepts

核心概念

Task-Model Fit Recognition

任务与模型匹配度的识别

Evaluate task-model fit before writing any code, because building automation on a fundamentally mismatched task wastes days of effort. Run every proposed task through these two tables to decide proceed-or-stop.
Proceed when the task has these characteristics:
CharacteristicRationale
Synthesis across sourcesLLMs combine information from multiple inputs better than rule-based alternatives
Subjective judgment with rubricsGrading, evaluation, and classification with criteria map naturally to language reasoning
Natural language outputWhen the goal is human-readable text, LLMs deliver it natively
Error toleranceIndividual failures do not break the overall system, so LLM non-determinism is acceptable
Batch processingNo conversational state required between items, which keeps context clean
Domain knowledge in trainingThe model already has relevant context, reducing prompt engineering overhead
Stop when the task has these characteristics:
CharacteristicRationale
Precise computationMath, counting, and exact algorithms are unreliable in language models
Real-time requirementsLLM latency is too high for sub-second responses
Perfect accuracy requirementsHallucination risk makes 100% accuracy impossible
Proprietary data dependenceThe model lacks necessary context and cannot acquire it from prompts alone
Sequential dependenciesEach step depends heavily on the previous result, compounding errors
Deterministic output requirementsSame input must produce identical output, which LLMs cannot guarantee
在编写任何代码之前评估任务与模型的匹配度,因为围绕根本不匹配的任务构建自动化会浪费数天的工作。每个拟议任务都应经过以下两张表,以决定继续还是停止。
任务具有以下特征时应继续:
特征原因
跨来源综合LLM 比基于规则的替代方案更擅长整合多个输入的信息
带评分标准的主观判断评分、评估和基于标准的分类天然适合语言推理
自然语言输出当目标是人类可读的文本时,LLM 原生就能生成此类内容
容错性单个失败不会破坏整体系统,因此可以接受 LLM 的非确定性
批处理各项目之间不需要对话状态,从而保持上下文简洁
模型训练中已具备领域知识模型已经拥有相关背景,可减少 prompt engineering 开销
任务具有以下特征时应停止:
特征原因
精确计算数学、计数和精确算法在语言模型中并不可靠
实时要求LLM 延迟过高,无法满足亚秒级响应
完美准确率要求幻觉风险使 100% 准确率无法实现
依赖专有数据模型缺少必要上下文,且无法仅通过 prompt 获得这些上下文
顺序依赖每一步都高度依赖上一步结果,误差会不断累积
确定性输出要求相同输入必须产生相同输出,而 LLM 无法保证这一点

The Manual Prototype Step

手动原型验证步骤

Always validate task-model fit with a manual test before investing in automation. Copy one representative input into the model interface, evaluate the output quality, and use the result to answer these questions:
  • Does the model have the knowledge required for this task?
  • Can the model produce output in the format needed?
  • What level of quality should be expected at scale?
  • Are there obvious failure modes to address?
Do this because a failed manual prototype predicts a failed automated system, while a successful one provides both a quality baseline and a prompt-design template. The test takes minutes and prevents hours of wasted development.
在投入自动化之前,务必通过手动测试验证任务与模型的匹配度。将一个代表性输入复制到模型界面中,评估输出质量,并用结果回答以下问题:
  • 模型是否掌握完成该任务所需的知识?
  • 模型能否生成所需格式的输出?
  • 在规模化应用时,应期待何种质量水平?
  • 是否存在需要处理的明显失败模式?
之所以要这样做,是因为手动原型失败通常预示着自动化系统也会失败;而手动原型成功则既能提供质量基线,也能提供 prompt 设计模板。这个测试只需几分钟,却能避免数小时的开发浪费。

Pipeline Architecture

流水线架构

Structure LLM projects as staged pipelines because separation of deterministic and non-deterministic stages enables fast iteration and cost control. Design each stage to be:
  • Discrete: Clear boundaries between stages so each can be debugged independently
  • Idempotent: Re-running produces the same result, preventing duplicate work
  • Cacheable: Intermediate results persist to disk, avoiding expensive re-computation
  • Independent: Each stage can run separately, enabling selective re-execution
Use this canonical pipeline structure:
acquire -> prepare -> process -> parse -> render
  1. Acquire: Fetch raw data from sources (APIs, files, databases)
  2. Prepare: Transform data into prompt format
  3. Process: Execute LLM calls (the expensive, non-deterministic step)
  4. Parse: Extract structured data from LLM outputs
  5. Render: Generate final outputs (reports, files, visualizations)
Stages 1, 2, 4, and 5 are deterministic. Stage 3 is non-deterministic and expensive. Maintain this separation because it allows re-running the expensive LLM stage only when necessary, while iterating quickly on parsing and rendering.
将 LLM 项目构造成分阶段流水线,因为分离确定性与非确定性阶段可实现快速迭代和成本控制。每个阶段都应设计为:
  • 离散:阶段之间边界清晰,以便独立调试
  • 幂等:重新运行会产生相同结果,防止重复工作
  • 可缓存:中间结果持久化到磁盘,避免昂贵的重复计算
  • 独立:每个阶段均可单独运行,从而支持选择性重新执行
使用以下标准流水线结构:
acquire -> prepare -> process -> parse -> render
  1. Acquire:从数据源获取原始数据(API、文件、数据库)
  2. Prepare:将数据转换为 prompt 格式
  3. Process:执行 LLM 调用(成本高且具有非确定性的阶段)
  4. Parse:从 LLM 输出中提取结构化数据
  5. 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, because file existence provides natural idempotency and human-readable debugging.
data/{id}/
  raw.json         # acquire stage complete
  prompt.md        # prepare stage complete
  response.md      # process stage complete
  parsed.json      # parse stage complete
Check if an item needs processing by checking whether the output file exists. Re-run a stage by deleting its output file and downstream files. Debug by reading the intermediate files directly. This pattern works because each directory is independent, enabling simple parallelization and trivial caching.
使用文件系统而非数据库或内存结构跟踪流水线状态,因为文件的存在天然提供幂等性,同时便于人类调试。
data/{id}/
  raw.json         # acquire stage complete
  prompt.md        # prepare stage complete
  response.md      # process stage complete
  parsed.json      # parse stage complete
通过检查输出文件是否存在,判断某个项目是否需要处理。要重新运行某个阶段,只需删除其输出文件及所有下游文件。调试时可以直接读取中间文件。该模式之所以有效,是因为每个目录都是独立的,从而便于简单并行化并实现简单缓存。

Structured Output Design

结构化输出设计

Design prompts for structured, parseable outputs because prompt design directly determines parsing reliability. Include these elements in every structured prompt:
  1. Section markers: Explicit headers or prefixes that parsers can match on
  2. Format examples: Show exactly what output should look like
  3. Rationale disclosure: State "I will be parsing this programmatically" so the model prioritizes format compliance
  4. Constrained values: Enumerated options, score ranges, and fixed formats
Build parsers that handle LLM output variations gracefully, because LLMs do not follow instructions perfectly. Use regex patterns flexible enough for minor formatting variations, provide sensible defaults when sections are missing, and log parsing failures for review rather than crashing.
设计 prompt 以生成可解析的结构化输出,因为 prompt 设计直接决定解析可靠性。每个结构化 prompt 都应包含以下元素:
  1. 分节标记:使用解析器可以匹配的明确标题或前缀
  2. 格式示例:准确展示输出应采用的格式
  3. 说明解析意图:明确说明“我将以程序方式解析此内容”,使模型优先遵守格式要求
  4. 受限值:枚举选项、分数范围和固定格式
构建能够妥善处理 LLM 输出差异的解析器,因为 LLM 并不会完美遵循指令。使用的正则表达式应足够灵活,以适应轻微的格式变化;在缺少某些部分时提供合理默认值;并记录解析失败以供审查,而不是直接崩溃。

Agent-Assisted Development

Agent 辅助开发

Use agent-capable models to accelerate development through rapid iteration: describe the project goal and constraints, let the agent generate initial implementation, test and iterate on specific failures, then refine prompts and architecture based on results.
Adopt these practices because they keep agent output focused and high-quality:
  • Provide clear, specific requirements upfront to reduce revision cycles
  • Break large projects into discrete components so each can be validated independently
  • Test each component before moving to the next to catch failures early
  • Keep the agent focused on one task at a time to prevent context degradation
使用具备 Agent 能力的模型,通过快速迭代加速开发:描述项目目标和约束,让 Agent 生成初始实现,针对具体失败进行测试和迭代,再根据结果改进 prompt 和架构。
采用以下实践,可以让 Agent 输出保持专注且质量更高:
  • 预先提供清晰、具体的要求,以减少修订轮次
  • 将大型项目拆分为独立组件,以便分别验证
  • 在进入下一组件前先测试当前组件,尽早发现故障
  • 让 Agent 每次专注于一项任务,防止上下文退化

Cost and Scale Estimation

成本与规模估算

Estimate LLM processing costs before starting, because token costs compound quickly at scale and late discovery of budget overruns forces costly rework. Use this formula:
Total cost = (items x tokens_per_item x price_per_token) + API overhead
For batch processing, estimate input tokens per item (prompt + context), estimate output tokens per item (typical response length), multiply by item count, and add 20-30% buffer for retries and failures.
Track actual costs during development. If costs exceed estimates significantly, reduce context length through truncation, use smaller models for simpler items, cache and reuse partial results, or add parallel processing to reduce wall-clock time.
在开始前估算 LLM 处理成本,因为 token 成本会随着规模迅速累积,而过晚发现预算超支会迫使团队进行代价高昂的返工。使用以下公式:
Total cost = (items x tokens_per_item x price_per_token) + API overhead
对于批处理,先估算每个项目的输入 token(prompt + context),再估算每个项目的输出 token(典型响应长度),将两者乘以项目总数,并为重试和失败预留 20% 至 30% 的缓冲空间。
在开发期间跟踪实际成本。如果成本明显超出估算,应通过截断来缩短上下文、对较简单的项目使用更小的模型、缓存并复用部分结果,或增加并行处理以缩短实际运行时间。

Detailed Topics

详细主题

Choosing Single vs Multi-Agent Architecture

选择单 Agent 或多 Agent 架构

Default to single-agent pipelines for batch processing with independent items, because they are simpler to manage, cheaper to run, and easier to debug. Escalate to multi-agent architectures only when one of these conditions holds:
  • Parallel exploration of different aspects is required
  • The task exceeds single context window capacity
  • Specialized sub-agents demonstrably improve quality on benchmarks
Choose multi-agent for context isolation, not role anthropomorphization. Sub-agents get fresh context windows for focused subtasks, which prevents context degradation on long-running tasks.
See
multi-agent-patterns
skill for detailed architecture guidance.
对于处理彼此独立项目的批处理任务,默认采用单 Agent 流水线,因为它们更易于管理、运行成本更低,也更方便调试。仅在满足以下条件之一时,才升级为多 Agent 架构:
  • 需要并行探索问题的不同方面
  • 任务超出单个上下文窗口的容量
  • 基准测试能够明确证明专用子 Agent 可以提升质量
选择多 Agent 架构是为了实现上下文隔离,而不是为了角色拟人化。子 Agent 会获得全新的上下文窗口,用于处理聚焦的子任务,从而防止长时间运行的任务发生上下文退化。
有关更详细的架构指导,请参阅
multi-agent-patterns
Skill。

Architectural Reduction

架构精简

Start with minimal architecture and add complexity only when production evidence proves it necessary, because over-engineered scaffolding often constrains rather than enables model performance.
Vercel's d0 case study reports improved success after reducing many specialized tools to two primitives: command execution and SQL (claim-project-development-vercel-d0-reduction). The file system agent pattern uses standard Unix utilities instead of custom exploration tools.
Reduce when:
  • The data layer is well-documented and consistently structured
  • The model has sufficient reasoning capability
  • Specialized tools are constraining rather than enabling
  • More time is spent maintaining scaffolding than improving outcomes
Add complexity when:
  • The 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
tool-design
skill for detailed tool architecture guidance.
从最小架构开始,仅当生产环境的证据证明确有必要时才增加复杂度,因为过度设计的脚手架往往会限制而非提升模型表现。
Vercel 的 d0 案例研究表明,将许多专用工具精简为两个原语——命令执行和 SQL——后,成功率有所提升(claim-project-development-vercel-d0-reduction)。文件系统 Agent 模式使用标准 Unix 工具,而不是自定义探索工具。
以下情况应精简:
  • 数据层文档完善且结构一致
  • 模型具备足够的推理能力
  • 专用工具正在限制模型,而不是帮助模型
  • 维护脚手架所花的时间多于改进结果所花的时间
以下情况应增加复杂度:
  • 底层数据混乱、不一致或文档不完善
  • 领域需要模型不具备的专门知识
  • 安全约束要求限制 Agent 的能力
  • 运维流程确实复杂,并且可以从结构化工作流中受益
有关更详细的工具架构指导,请参阅
tool-design
Skill。

Iteration and Refactoring

迭代与重构

Plan for multiple architectural iterations from the start, because production agent systems at scale always require refactoring. 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 by following these practices:
  • Keep architecture simple and unopinionated so refactoring is cheap
  • Test across model generations to verify the harness is not limiting performance
  • Design systems that benefit from model improvements rather than locking in limitations
从一开始就规划多轮架构迭代,因为大规模生产 Agent 系统始终需要重构。Manus 自发布以来已对其 Agent 框架进行了五次重构。The Bitter Lesson(苦涩的教训)指出,为当前模型限制而添加的结构,会随着模型进步逐渐成为限制。
通过以下实践为变化做好准备:
  • 保持架构简单且不预设方向,使重构成本较低
  • 跨模型代际进行测试,以验证执行框架没有限制性能
  • 设计能够受益于模型改进的系统,而不是将当前限制固化在系统中

Practical Guidance

实践指导

Project Planning Template

项目规划模板

Follow this template in order, because each step validates assumptions before the next step invests effort.
  1. Task Analysis
    • Define the input and desired output explicitly
    • Classify: synthesis, generation, classification, or analysis
    • Set an acceptable error rate based on business impact
    • Estimate the value per successful completion to justify costs
  2. Manual Validation
    • Test one representative example with the target model
    • Evaluate output quality and format against requirements
    • Identify failure modes that need parser hardening or prompt revision
    • Estimate tokens per item for cost projection
  3. Architecture Selection
    • Choose single pipeline vs multi-agent based on the criteria above
    • Identify required tools and data sources
    • Design storage and caching strategy using file-system state
    • Plan parallelization approach for the process stage
  4. Cost Estimation
    • Calculate items x tokens x price with a 20-30% buffer
    • Estimate development time for each pipeline stage
    • Identify infrastructure requirements (API keys, storage, compute)
    • Project ongoing operational costs for production runs
  5. Development Plan
    • Implement stage-by-stage, testing each before proceeding
    • Define a testing strategy per stage with expected outputs
    • Set iteration milestones tied to quality metrics
    • Plan deployment approach with rollback capability
按以下顺序遵循该模板,因为每个步骤都会在下一步投入精力之前验证相应假设。
  1. 任务分析
    • 明确输入和期望输出
    • 归类为综合、生成、分类或分析
    • 根据业务影响设定可接受的错误率
    • 估算每次成功完成所创造的价值,以论证成本的合理性
  2. 手动验证
    • 使用目标模型测试一个代表性示例
    • 根据需求评估输出质量和格式
    • 识别需要强化解析器或修改 prompt 的失败模式
    • 估算每个项目的 token 数,以预测成本
  3. 架构选择
    • 根据上述标准选择单流水线或多 Agent 架构
    • 确定所需工具和数据源
    • 使用文件系统状态设计存储和缓存策略
    • 规划处理阶段的并行化方式
  4. 成本估算
    • 使用“项目数 × token 数 × 单价”计算成本,并预留 20% 至 30% 的缓冲空间
    • 估算每个流水线阶段的开发时间
    • 确定基础设施需求(API 密钥、存储、计算资源)
    • 预测生产运行的持续运营成本
  5. 开发计划
    • 按阶段实施,在进入下一阶段前先测试当前阶段
    • 为每个阶段定义测试策略及预期输出
    • 设置与质量指标关联的迭代里程碑
    • 规划具备回滚能力的部署方式

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: many specialized tools with lower measured success and longer average execution.
After: two tools (bash + SQL) with higher measured success and shorter average execution (claim-project-development-vercel-d0-reduction).
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 Time Capsule)
任务:结合事后视角的评分机制,分析十年前的 930 条 HN 讨论。
架构:
  • 5 阶段流水线:fetch -> prompt -> analyze -> parse -> render
  • 文件系统状态:data/{date}/{item_id}/,其中包含各阶段的输出文件
  • 结构化输出:6 个部分,并采用明确的格式要求
  • 并行执行:使用 15 个 worker 执行 LLM 调用
结果:总成本为 58 美元,执行时间约 1 小时,输出为静态 HTML。
示例 2:架构精简(Vercel d0)
任务:用于内部分析的 Text-to-SQL Agent。
精简前:包含许多专用工具,实测成功率较低,平均执行时间较长。
精简后:仅使用两个工具(bash + SQL),实测成功率更高,平均执行时间更短(claim-project-development-vercel-d0-reduction)。
关键洞察:语义层本身已经是优质文档。Claude 只需要能够直接读取文件即可。
有关详细分析,请参阅案例研究。

Guidelines

指南

  1. Validate task-model fit with manual prototyping before building automation
  2. Structure pipelines as discrete, idempotent, cacheable stages
  3. Use the file system for state management and debugging
  4. Design prompts for structured, parseable outputs with explicit format examples
  5. Start with minimal architecture; add complexity only when proven necessary
  6. Estimate costs early and track throughout development
  7. Build robust parsers that handle LLM output variations
  8. Expect and plan for multiple architectural iterations
  9. Test whether scaffolding helps or constrains model performance
  10. Use agent-assisted development for rapid iteration on implementation
  1. 在构建自动化之前,通过手动原型验证任务与模型的匹配度
  2. 将流水线设计为离散、幂等、可缓存的阶段
  3. 使用文件系统进行状态管理和调试
  4. 设计带有明确格式示例的、可解析的结构化输出 prompt
  5. 从最小架构开始,仅在确有必要时才增加复杂度
  6. 尽早估算成本,并在开发全程持续跟踪
  7. 构建能够处理 LLM 输出差异的稳健解析器
  8. 预期并规划多轮架构迭代
  9. 测试脚手架是在提升还是限制模型表现
  10. 使用 Agent 辅助开发快速迭代实现

Gotchas

常见陷阱

  1. Skipping manual validation: Building automation before verifying the model can do the task wastes significant time when the approach is fundamentally flawed. Always run one representative example through the model interface first.
  2. Monolithic pipelines: Combining all stages into one script makes debugging and iteration difficult. Separate stages with persistent intermediate outputs so each can be re-run independently.
  3. Over-constraining the model: Adding guardrails, pre-filtering, and validation logic that the model could handle on its own reduces performance. Test whether scaffolding helps or hurts before keeping it.
  4. Ignoring costs until production: Token costs compound quickly at scale. Estimate and track from the beginning to avoid budget surprises that force architectural rework.
  5. Perfect parsing requirements: Expecting LLMs to follow format instructions perfectly leads to brittle systems. Build robust parsers that handle variations and log failures for review.
  6. Premature optimization: Adding caching, parallelization, and optimization before the basic pipeline works correctly wastes effort on code that may be discarded during iteration.
  7. Model version lock-in: Building pipelines that only work with one specific model version creates fragile systems. Test across model generations and abstract the LLM call layer so models can be swapped without rewriting pipeline logic.
  8. Evaluation-less deployment: Shipping agent pipelines without measuring output quality means regressions go undetected. Define quality metrics during development and run evaluation checks before and after every model or prompt change.
  9. Provenance drift: Raw inputs, intermediate outputs, and final proposals separated across ad hoc folders become impossible to audit. Keep each pipeline run in a single directory with source evidence, transformations, validation reports, and decisions.
  1. 跳过手动验证:在尚未验证模型能否完成任务之前就构建自动化,会在方法根本不可行时浪费大量时间。始终先通过模型接口运行一个代表性示例。
  2. 单体式流水线:将所有阶段合并到一个脚本中,会使调试和迭代变得困难。应分离阶段并持久化中间输出,使每个阶段都能独立重新运行。
  3. 过度约束模型:添加模型本可自行处理的护栏、预过滤和验证逻辑会降低性能。在保留这些机制前,先测试脚手架究竟是有帮助还是有害。
  4. 忽视成本直至生产阶段:token 成本会随着规模迅速累积。从一开始就估算并跟踪成本,避免预算超支导致架构返工。
  5. 对完美解析的过高要求:期待 LLM 完美遵循格式指令会形成脆弱的系统。应构建能够处理差异的稳健解析器,并记录失败以供审查。
  6. 过早优化:在基础流水线尚未正确运行前加入缓存、并行化和优化,会浪费可能因迭代而被丢弃的代码精力。
  7. 模型版本锁定:构建只能在某个特定模型版本上运行的流水线会形成脆弱的系统。应跨模型代际进行测试,并抽象 LLM 调用层,以便在不重写流水线逻辑的情况下替换模型。
  8. 无评估部署:在未测量输出质量的情况下发布 Agent 流水线,会导致回归问题无法被发现。应在开发期间定义质量指标,并在每次更改模型或 prompt 前后运行评估检查。
  9. 溯源漂移:如果原始输入、中间输出和最终提案分散在临时创建的各个文件夹中,将无法进行审计。应将每次流水线运行保存在同一个目录中,并包含来源证据、转换过程、验证报告和决策记录。

Integration

集成

This skill owns project-shape and pipeline decisions. Adjacent decisions are owned elsewhere:
  • tool-design
    : the per-tool interface layer (descriptions, schemas, response formats, error messages, MCP namespacing, individual tool consolidation). If the question is "what should this specific tool look like" rather than "what should the pipeline look like," route there.
  • multi-agent-patterns
    : agent topology decisions (supervisor vs swarm vs hierarchical, handoff protocols, context isolation across agents). This skill picks single-vs-multi at the project level; the topology details belong to multi-agent-patterns.
  • harness-engineering
    : the autonomous control loop around the project (locked metrics, novelty gates, run state machine, human approval boundaries). If the question is "how do we make this run unattended for days," route there.
  • context-fundamentals
    : the conceptual frame for context constraints that inform prompt design at every stage.
  • evaluation
    : outcome measurement and quality gates for pipeline runs.
  • context-compression
    : when long-running pipeline stages produce trajectories that need summarization.
本 Skill 负责项目形态和流水线决策。相邻决策由其他 Skill 负责:
  • tool-design
    :单个工具的接口层(描述、schema、响应格式、错误消息、MCP 命名空间、单个工具整合)。如果问题是“这个具体工具应该是什么样”,而不是“流水线应该是什么样”,应转交此处。
  • multi-agent-patterns
    :Agent 拓扑决策(supervisor、swarm 或 hierarchical、交接协议、跨 Agent 的上下文隔离)。本 Skill 在项目层面选择单 Agent 或多 Agent;拓扑细节属于
    multi-agent-patterns
    。
  • harness-engineering
    :围绕项目的自主控制循环(锁定指标、新颖性门控、运行状态机、人类审批边界)。如果问题是“如何让系统无人值守地运行数天”,应转交此处。
  • context-fundamentals
    :为每个阶段的 prompt 设计提供信息的上下文约束概念框架。
  • evaluation
    :流水线运行的结果测量和质量门控。
  • context-compression
    :长时间运行的流水线阶段产生需要摘要的轨迹时使用。

References

参考资料

Internal references:
  • Case Studies - Read when: evaluating architecture tradeoffs or reviewing real-world pipeline implementations (Karpathy HN Capsule, Vercel d0, Manus patterns)
  • Pipeline Patterns - Read when: designing a new pipeline stage layout, choosing caching strategies, or debugging stage boundaries
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 HN Capsule、Vercel d0、Manus 模式)
  • 流水线模式 - 阅读时机:设计新的流水线阶段布局、选择缓存策略或调试阶段边界
本 Skill 集合中的相关 Skill:
  • tool-design - 工具架构与精简模式
  • multi-agent-patterns - 何时使用多 Agent 架构
  • evaluation - 输出评估框架
外部资源:

Skill Metadata

Skill 元数据

Created: 2025-12-25 Last Updated: 2026-05-15 Author: Agent Skills for Context Engineering Contributors Version: 1.3.0
创建时间:2025-12-25 最后更新时间:2026-05-15 作者:Agent Skills for Context Engineering Contributors 版本:1.3.0