requirements 轻量级流程

requirements 工作流概述

requirements 是 PinableAgents 中最轻量的开发工作流，专为快速原型和小型功能开发设计。它将传统的需求分析、设计、实现、测试四个阶段压缩为一条精简的管线（Pipeline），在保证基本质量的前提下最大化开发速度。

requirements 工作流仅由三个核心智能体驱动：requirements-generate（需求收集与规格生成）、requirements-code（直接代码实现）、requirements-testing（快速验证）。没有独立的架构设计阶段，没有多轮审查机制，也没有外部记忆系统——一切从简，直奔结果。

这种设计不是偷工减料，而是对特定场景的精准匹配。当你需要在半小时内搭建一个 CLI 工具的原型，或者为一个内部项目快速添加一个简单的 API 端点时，启动 bmad 的六角色团队显然是杀鸡用牛刀。requirements 工作流为这些场景提供了恰当的流程力度。

选择工作流的核心原则是"匹配"而非"最好"。requirements 不是一个降级版的 do，而是一个为速度场景优化的独立工作流。在正确的场景下使用它，效率远超其他工作流。

设计哲学：速度优先

requirements 工作流的设计遵循三个核心原则：

1. 最少阶段：将流程压缩到不可再减的最少阶段数。每个阶段的存在都有明确的必要性，去掉任何一个阶段都会导致产出质量无法接受。
2. 隐式决策：在不影响结果质量的前提下，尽可能多地采用隐式决策（基于约定和默认值），减少需要用户确认的决策点。例如，API 端点的路径命名自动遵循 RESTful 约定，无需用户逐一确认。
3. 渐进增强：requirements 产出的代码是可以后续增强的起点，而非最终版本。它保证功能正确性和基本可维护性，但不追求极致的性能优化或边界条件覆盖。后续可以通过 do 或 sparv 工作流进行增强。

三个核心智能体

智能体	职责	输入	输出
requirements-generate	需求收集、结构化、规格生成	用户描述 + 项目上下文	轻量规格文档
requirements-code	代码实现、依赖安装	轻量规格文档	可运行的代码
requirements-testing	快速验证、冒烟测试	代码实现 + 规格文档	测试结果报告

三个智能体以线性管线方式连接，每个智能体的输出直接作为下一个智能体的输入。没有回溯机制——如果测试失败，requirements-code 直接修复并重新提交，无需回退到 requirements-generate。

需求收集阶段

需求收集由 requirements-generate 智能体的第一个子任务完成。它通过分析用户的任务描述，结合项目上下文（.pinable/context.md、package.json、目录结构），快速建立对任务的理解。

收集策略

与 do 工作流的 Clarify 阶段不同，requirements 的需求收集不会主动向用户提问。它采用"最大合理推断"策略：对于用户未明确指定的细节，智能体基于项目上下文和行业惯例做出最合理的推断，并在规格文档中标注这些推断，让用户可以在后续快速调整。

# 需求收集日志示例
[req:gather] 分析任务描述: "写一个文件备份 CLI 工具"
[req:gather] 项目上下文: Go 项目，使用 cobra 作为 CLI 框架
[req:gather] 推断: 备份目标为本地文件系统 (用户未指定远程)
[req:gather] 推断: 使用增量备份策略 (行业惯例)
[req:gather] 推断: 配置文件格式为 YAML (项目已有 YAML 依赖)

规格生成阶段

规格生成是 requirements-generate 智能体的第二个子任务。它将收集到的需求和推断转化为轻量规格文档。与 sparv 的精确规格不同，requirements 的规格文档更简洁，聚焦于功能点和核心接口，省略详细的错误码定义和状态机描述。

轻量规格文档模板

# 功能规格：文件备份 CLI 工具

## 核心命令
- backup <source> <destination>  增量备份源目录到目标目录
- restore <backup> <target>      从备份恢复到指定目录
- list <backup-dir>              列出备份历史
- config init                     初始化配置文件

## 关键行为
- 增量备份基于文件修改时间戳
- 备份元数据存储在目标目录的 .backup-meta.json
- 支持 --exclude 参数排除指定模式的文件
- 默认压缩算法: gzip

## 推断标注 [需确认]
- 最大单文件大小限制: 2GB
- 备份保留策略: 保留最近 10 个版本

代码实现阶段

requirements-code 智能体接收轻量规格文档后，直接进入编码实现。该智能体的编码策略是"先跑通，再优化"——优先保证所有核心功能可用，然后在时间允许的情况下进行基本的代码清理。

实现优先级

1. 项目脚手架（目录结构、入口文件、依赖安装）
2. 核心功能实现（按规格文档的命令列表顺序）
3. 基本错误处理（输入验证、文件系统错误）
4. 配置和帮助文本

// 由 requirements-code 生成的 CLI 入口示例
package main

import (
    "github.com/spf13/cobra"
    "backup-tool/cmd"
)

func main() {
    root := &cobra.Command{
        Use:   "backup-tool",
        Short: "简单高效的文件增量备份工具",
    }

    root.AddCommand(cmd.BackupCmd())
    root.AddCommand(cmd.RestoreCmd())
    root.AddCommand(cmd.ListCmd())
    root.AddCommand(cmd.ConfigCmd())

    if err := root.Execute(); err != nil {
        os.Exit(1)
    }
}

快速验证阶段

requirements-testing 智能体执行快速验证，确保核心功能正常工作。与 do 或 bmad 工作流的全面测试不同，requirements 的测试聚焦于冒烟测试（Smoke Test）和快乐路径验证。

测试策略

• 冒烟测试：每个命令能否正常启动和退出
• 快乐路径：核心场景端到端验证（备份-恢复-验证）
• 基本错误处理：无效参数、目录不存在等常见错误

# 快速验证输出
[req:test] 冒烟测试: backup 命令 ✓ (正常退出)
[req:test] 冒烟测试: restore 命令 ✓ (正常退出)
[req:test] 冒烟测试: list 命令 ✓ (正常退出)
[req:test] 快乐路径: 备份->恢复->对比 ✓ (文件一致)
[req:test] 错误处理: 无效源目录 ✓ (正确报错)
[req:test] 结果: 5/5 通过

requirements 与 do 工作流对比

理解何时使用 requirements、何时使用 do 是高效使用 PinableAgents 的关键。

维度	requirements	do
阶段数	3 个（收集-实现-验证）	7 个（完整流程）
智能体数	3 个	7 个
执行时间	5-15 分钟	20-60 分钟
需求精度	允许推断，隐式决策	要求明确，主动澄清
测试覆盖	冒烟测试 + 快乐路径	全面测试，85%+ 覆盖
回溯机制	无（直接修复前进）	有（阶段间回退）
代码审查	无独立审查阶段	五维评估框架
适用规模	1-3 文件变更	1-10 文件变更
最佳场景	原型、内部工具、简单功能	生产功能、面向用户的特性

经验法则：如果任务的描述能用一句话说清楚，用 requirements；如果需要一段话来说明，用 do；如果需要一页纸来描述，用 bmad。

实战：快速原型 CLI 工具

以下演示使用 requirements 工作流在 10 分钟内构建一个 JSON 格式化 CLI 工具。

启动工作流

pinable-agents run requirements \
  --task "写一个 JSON 格式化 CLI 工具，支持从文件和 stdin 读取，输出美化后的 JSON"

自动推进过程

requirements-generate 在 90 秒内完成需求收集和规格生成。推断了以下默认行为：缩进使用 2 个空格、支持语法高亮输出（检测到终端环境）、错误输出到 stderr。

requirements-code 在 3 分钟内完成实现，产出三个文件：main.go（入口和参数解析）、formatter.go（格式化逻辑）、highlight.go（语法高亮）。自动运行 go mod init 和 go mod tidy 安装依赖。

requirements-testing 在 2 分钟内完成验证：文件输入格式化通过、stdin 管道输入通过、无效 JSON 错误处理通过、空输入处理通过。

# 使用生成的工具
echo '{"name":"test","value":42}' | json-fmt
# 输出：
# {
#   "name": "test",
#   "value": 42
# }

# 从文件读取
json-fmt input.json

# 输出到文件
json-fmt input.json -o output.json

管线配置选项

requirements 工作流支持通过配置文件或命令行参数自定义管线行为。

# .pinable/workflows/requirements.json
{
  "requirements": {
    "inference_level": "aggressive",
    "test_strategy": "smoke",
    "max_files": 5,
    "auto_install_deps": true,
    "language_preference": "go",
    "style_guide": "project",
    "skip_testing": false,
    "output_format": "minimal"
  }
}

配置项说明

配置项	可选值	说明
inference_level	conservative / balanced / aggressive	推断激进程度，aggressive 减少确认提问
test_strategy	smoke / basic / standard	测试策略粒度
max_files	1-10	最大生成文件数，超过建议使用 do
auto_install_deps	true / false	是否自动安装依赖
skip_testing	true / false	跳过测试阶段（不推荐）

需求模板与预设

requirements 内置了一组常用场景的需求模板，可以进一步加速开发过程。

# 使用内置模板
pinable-agents run requirements --template cli-tool \
  --task "日志分析工具，支持按时间和级别过滤"

pinable-agents run requirements --template rest-endpoint \
  --task "用户个人资料更新接口"

pinable-agents run requirements --template cron-job \
  --task "每日数据库备份任务"

# 查看可用模板
pinable-agents templates list --workflow requirements

可用模板列表

• cli-tool：命令行工具脚手架，包含参数解析、帮助文本、配置文件
• rest-endpoint：RESTful API 端点，包含路由、处理器、请求验证
• cron-job：定时任务，包含调度器、执行逻辑、日志记录
• middleware：中间件组件，包含链式调用和上下文传递
• data-migration：数据迁移脚本，包含正向和回滚逻辑

CLI 命令参考

# 基本用法
pinable-agents run requirements --task "任务描述"

# 使用模板
pinable-agents run requirements --template cli-tool --task "任务描述"

# 自定义配置
pinable-agents run requirements --task "任务描述" \
  --inference aggressive \
  --test-strategy basic \
  --max-files 3

# 跳过测试（快速模式）
pinable-agents run requirements --task "任务描述" --skip-testing

# 指定后端
pinable-agents run requirements --task "任务描述" \
  --backend claude --model claude-opus-4-6

# 输出规格文档但不执行实现（用于审查）
pinable-agents run requirements --task "任务描述" --dry-run

# 从已有规格文档直接实现
pinable-agents run requirements --spec ./spec.md --skip-gather