Speco

Speco — Spec for Objective. (助您达成目标的路书)

Speco 是一个以“结构化上下文供给”为核心的、AI 编程项目开发工具套件。它通过首先确保“价值正确”，再以“测试驱动”和“架构治理”为纪律，最终实现高效、可靠、可追溯的“技术正确”。

目录

• 为什么需要 Speco？
• 核心理念：上下文工程
• Speco 完整流程
• 核心命令一览
• 六大核心支柱
• 快速开始 (即将推出)
• 项目状态
• 如何贡献

为什么需要 Speco？

在 AI 辅助开发的时代，软件工程的核心瓶颈已不再是“编写代码的速度”，而是“如何确保 AI 在正确的上下文中，编写出正确的代码”。

spec-kit 等优秀的工具通过“规格驱动开发 (SDD)”，在“技术正确”的道路上迈出了革命性的一步。然而，它们在复杂项目中依然存在结构性局限，例如项目全景缺失、产品管理脱节、跨功能依赖困难以及需求对齐困难。

speco 的诞生，正是为了解决这些更高维度的问题。我们相信，一个先进的 AI 开发流程，必须首先聚焦于“价值正确”，确保团队始终航行在正确的航道上；然后再利用强大的自动化引擎，确保航船本身（技术实现）是坚固、高效且可靠的。

核心理念：上下文工程

speco 的核心创新是建立了一套完整的**“结构化上下文供给 (Structured Context Provisioning)”**体系。我们不去重新发明 AI，而是为现有的、强大的 AI 工具（如 AI IDE, AI Coding CLI）设计一套最高效、最精准的“航空管制与地面保障系统”。

这个系统通过一个多层次的上下文环境，为 AI 的每一次行动都提供了恰到好处的引导：

• 全局原则层 (constitution.md): Agent 的“世界观”和“行为准则”。
• 架构蓝图层 (components/ Registry): Agent 的“架构地图”。
• 任务指令层 (commands/ & templates/): Agent 的“任务手册”和“施工图纸”。
• 即时上下文层 (AGENTS.md): Agent 的“本地便签”。

Speco 完整流程

speco 将一个想法从诞生到交付的全过程，划分为六个核心阶段，并由一系列 AI 辅助命令来驱动。

| 阶段 | 名称 | 核心命令 | 目标 | | :--- | :--- | :--- | :--- | | 阶段 0 | 战略规划 | /roadmap, /epic | 将商业愿景转化为结构化的产品战略 | | 阶段 1 | 架构定义 | /architect | 将史诗转化为明确的架构框架 | | 阶段 2 | 故事与规格 | /story, /spec | 将史诗分解为故事，并转化为工程契约 | | 阶段 3 | 并行规划 | /test-plan, /plan | 并行完成测试规划和技术规划 | | 阶段 4 | 任务与实现 | /tasks | 将所有蓝图分解为可执行任务并编码 | | 阶段 5 | 验证与交付 | (CI/CD & Manual) | 集成、验证并向用户交付价值 |

核心命令一览

• /init: 初始化一个 speco 项目，创建所有必要的目录和模板。
• /roadmap: 协作式创建和更新项目的核心战略文档 roadmap.md。
• /epic: 辅助创建、更新和管理 epics/ 目录下的史诗文件。
• /story: 将简单的用户故事描述，扩展为包含 GWT 验收标准的 story.md。
• /architect: 对一个史诗进行技术评估，定义其架构边界，并更新系统的组件注册中心。
• /spec: 将 story.md 转化为无歧义的、包含 FR/NFR 的工程契约 spec.md。
• /test-plan: 根据 spec.md 生成一份详细的测试计划，定义所有层级的测试用例。
• /plan: 根据 spec.md 和架构地图，生成一套完整的“技术设计文档集”。
• /tasks: 将所有规划蓝图，自动分解为带有精确依赖关系的 tasks.md。

六大核心支柱

1. 故事驱动开发 (Story-Driven Development): 以用户故事为所有开发活动的唯一价值源头。
2. 端到端可追溯性 (End-to-End Traceability): 确保从战略到代码的每一个环节都有清晰、可追溯的链接。
3. 测试驱动开发 (Test-Driven Development): 将质量内建于流程，坚持“测试先行”的纪律。
4. 关注点分离 (Separation of Concerns): 彻底分离业务与工程、过程与产物、规划与实现。
5. 架构治理与领域驱动设计 (Architectural Governance & DDD): 对系统架构进行前置的、有意识的治理。
6. 人机协作 (Human-AI Collaboration): 将 AI 定位为“合作伙伴”，赋能所有团队成员。

快速开始

# 安装 speco CLI
npm install -g speco-dev

# 初始化您的项目
mkdir my-new-project
cd my-new-project
speco init --ide cursor

# 开始您的战略规划
cursor .
# 在 Cursor 中输入 /roadmap ...

初始化之后，您的项目目录结构将会如下：

.
├── .[IDE_NAME]/                # AI IDE 特定的配置目录
│   ├── commands/               # (例如 .cursor/commands)
│   │   ├── architect.md（or .mdc）
│   │   └── ... (所有命令的SOP)
│   └── rules/                 # (例如 .cursor/rules)
│       ├──constitution.md     # 项目宪法 (设置为 alwaysApply: true)
│       └── ...                # 其他规则（例如 .mdc）
└── .speco/                    # Speco 流程的核心资产目录
    ├── scripts/               # 自动化脚本与工具
    ├── product/
    │   ├── backlog.md         # 需求池（Backlog）
    │   └── epics/
    ├── registry/
    │   ├── components/
    │   └── errors/
    ├── specs/
    ├── stories/
    ├── standards/              # 全局的“工程标准”法典 
    │   └── testing/
    │       ├── ci-cd/
    │       └── test-configs/
    └── templates/              # 所有“产出物”的蓝图模板
        ├── roadmap.template.md
        ├── epic.template.md
        └── ... (所有其他模板)

📄 许可证

本项目采用 Apache License 2.0 开源协议。

Speco - Spec for Objective. 助您达成目标的路书。