用途
Auto-Claude Spec 用于为自主构建创建和管理规格（spec）。规格是 Auto-Claude 构建的基础，定义要构建的内容、验收标准、来自现有代码库的上下文以及实现计划。该技能适用于创建功能规格、理解规格流水线阶段、修改需求或管理规格的场景。
主要能力
规格流水线阶段
动态阶段选择：Auto-Claude 会根据任务复杂度自动选择阶段。
简单（SIMPLE）任务为 3 个阶段：发现→快速规格→验证。
标准（STANDARD）任务为 6-7 个阶段：发现→需求→[研究]→上下文→规格→计划→验证。
复杂（COMPLEX）任务为 8 个阶段：包含研究与自我批判阶段的完整流水线。
各阶段说明：
- 发现阶段：以交互方式收集用户需求、提出澄清问题、识别范围与约束。
- 需求阶段：将需求结构化为 JSON 格式、定义验收标准、列出技术约束。
- 研究阶段（标准/复杂）：验证外部集成、检查 API 兼容性、研究最佳实践。
- 上下文阶段：分析现有代码库、识别相关文件、映射依赖关系。
- 规格编写阶段：创建详细的 spec.md、记录技术方案、列出受影响的组件。
- 计划阶段：创建实现计划、将工作拆分为子任务、定义阶段依赖。
- 批判阶段（仅复杂）：使用 ultrathink 进行自我审查、识别潜在问题、提出改进建议。
- 验证阶段：验证所有产物、检查完整性、为构建做准备。
创建规格
交互模式（推荐）：
cd apps/backend
python spec_runner.py --interactive
系统会询问你的功能/任务、澄清需求、分析代码库并生成完整规格。
从任务描述创建：
# 快速创建规格
python spec_runner.py --task "Add dark mode toggle to settings page"
# 强制指定复杂度
python spec_runner.py --task "Add payment integration" --complexity complex
继续中断的规格：
# 从中断处恢复
python spec_runner.py --continue 001-feature-name
规格结构
目录布局：
.auto-claude/specs/001-feature-name/
├── spec.md # 主规格文档
├── requirements.json # 结构化需求
├── context.json # 代码库上下文
├── implementation_plan.json # 基于子任务的计划
├── discovery.json # 初始发现数据
├── research.json # 研究发现（如适用）
└── validation_report.json # 验证结果
requirements.json 格式：
{
"title": "Feature Title",
"description": "Detailed description",
"acceptance_criteria": [
"User can do X",
"System responds with Y"
],
"constraints": [
"Must work on mobile",
"Must be accessible"
],
"priority": "high",
"complexity": "standard"
}
implementation_plan.json 格式：
{
"spec_id": "001-feature-name",
"subtasks": [
{
"id": 1,
"title": "Create data model",
"description": "Add User schema to database",
"status": "pending",
"dependencies": [],
"files": ["src/models/user.ts"]
},
{
"id": 2,
"title": "Implement API endpoint",
"description": "Create /api/users route",
"status": "pending",
"dependencies": [1],
"files": ["src/routes/users.ts"]
}
],
"total_subtasks": 2,
"completed": 0
}
使用方式
编写良好需求
好的示例："Add user authentication using Google OAuth with: Login button in header, Protected routes for /dashboard/*, User profile stored in database, Session management with cookies"。
不好的示例："Add login feature"。
复杂度选择
简单：1-2 个文件，UI 调整、文本修改、简单缺陷修复。
标准：3-10 个文件，新功能、组件新增。
复杂：10+ 个文件，外部集成、架构变更。
规格审查技巧
运行构建之前：检查验收标准是否可测试；审查受影响的组件是否已全部识别；验证依赖项外部服务是否可用；确认范围是否合适。
管理规格
列出所有规格：python run.py --list
查看规格状态：cat .auto-claude/specs/001-feature/spec.md 或 cat .auto-claude/specs/001-feature/implementation_plan.json
修改规格：直接编辑 spec.md 文件，然后重新验证：python validate_spec.py --spec-dir .auto-claude/specs/001-feature --checkpoint all
删除规格：rm -rf .auto-claude/specs/001-feature，或通过 CLI 丢弃（包含 worktree 清理）：python run.py --spec 001 --discard
高级用法
自定义提示词：修改 apps/backend/prompts/ 中的提示词文件，包括 spec_gatherer.md（发现阶段）、spec_researcher.md（研究阶段）、spec_writer.md（规格编写）、spec_critic.md（自我批判）、spec_quick.md（简单规格创建）。
批量创建规格：从文件读取任务并循环创建。
规格模板：可在 apps/backend/templates/ 中创建自定义模板。
故障排除
规格创建失败：启用调试模式 DEBUG=true python spec_runner.py --interactive，或查看日志 cat .auto-claude/logs/spec_runner.log。
需求无效：验证规格结构 python validate_spec.py --spec-dir .auto-claude/specs/001-feature --checkpoint requirements。
上下文发现问题：重新运行上下文分析 python spec_runner.py --continue 001-feature。
适用场景
需要为自主构建定义功能规格时；需要理解规格流水线各阶段时；需要修改需求或管理规格时；创建功能规格、管理规格生命周期、排查规格创建问题时。
限制
具体支持的操作系统、运行时版本、依赖安装方式等信息暂未提供。