# SpekLess：AI 编码 Agent 的轻量级规格优先开发工作流

> SpekLess 是一个为 AI 编码 Agent（如 Claude Code）设计的轻量级规格优先开发工作流。它通过单一的设计文档（spec.md）和追加式工作日志（execution.md），配合十个斜杠命令技能，实现澄清→规划→实现→验证的完整生命周期，无需状态机、锁文件或检查点文件。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-04-09T20:10:26.000Z
- 最近活动: 2026-04-09T20:26:51.866Z
- 热度: 157.7
- 关键词: AI 编码, Claude Code, 规格驱动, 开发工作流, 斜杠命令, 文档即状态, Agent 工作流
- 页面链接: https://www.zingnex.cn/forum/thread/spekless-ai-agent
- Canonical: https://www.zingnex.cn/forum/thread/spekless-ai-agent
- Markdown 来源: ingested_event

---

# SpekLess：AI 编码 Agent 的轻量级规格优先开发工作流

## 为什么需要 SpekLess？

在 Claude Code 等 AI 编码工具中进行规格驱动开发很有价值，但现有工具存在摩擦：

### GSD（GitHub Spec-Driven）的问题
- **Token 消耗高**：每个工作流步骤（researcher、planner、plan-checker、executor、verifier、integration-checker、nyquist-auditor...）都启动冷启动的子 Agent，重新读取文件、写入自己的工件
- **强制原子提交**：污染 git 历史，锁定你在刚性状态机中

### GitHub SpecKit 的问题
- 将一个功能分散在三个文件（`spec.md`、`plan.md`、`tasks.md`）中
- 使用模板驱动的流程，不与 Claude Code 技能集成

### 纯 ADR/RFC 文档的问题
- 人类可读，但 Agent 无法获得帮助——每次讨论、规划和验证都是临时性的

## SpekLess 的解决方案

SpekLess 是一个最小系统，保留好的部分，去除其余：

### 核心设计原则

1. **每个功能一个活的 `spec.md`**
   - 像 RFC 一样阅读
   - 包含 Context、Discussion、Plan、Verification 章节
   - 一个功能的所有内容都在一个地方

2. **追加式 `execution.md` 工作日志**
   - 人类可读的实际工作叙述
   - 与规格并存
   - 取代原子提交纪律，不强制按他人节奏提交

3. **扁平的功能列表**
   - 没有里程碑→阶段→任务的嵌套层次
   - 大工作通过 `part_of:` 前元字段分解为兄弟文档

4. **十个技能，而非三十个子 Agent**
   - 单一主 Agent 通过斜杠命令驱动一切
   - 子 Agent 仅用作广泛代码库读取的上下文防火墙，从不作为流水线步骤

5. **随时干预**
   - 文档就是状态
   - 没有 STATE.md、没有检查点文件、没有锁定步骤顺序
   - 编辑任何章节，重新运行任何技能，随时进行

## 十个技能详解

### 入口点（启动时选择其一）

| 技能 | 使用场景 |
|-----|---------|
| `/spek:kickoff` | 启动绿地项目。运行扩展的 PRD 风格讨论，写入 `.specs/project.md`，并提议搭建初始功能文件夹 |
| `/spek:new` | 向任何项目添加新功能。创建骨架功能文件夹，仅此而已 |
| `/spek:adopt` | 追溯记录已存在的代码。读取实际文件（通过 Explore 子 Agent），反向工程 Context 和 Plan 章节，将所有任务标记为已完成。SpekLess 独有 |

### 工作流（按顺序使用）

| 技能 | 功能 |
|-----|------|
| `/spek:discuss` | 对话式探索。写入 `## Context` 和 `## Discussion`。主动发现歧义，而非等待你主动提供 |
| `/spek:plan` | 写入 `## Plan` —— 带复选框的任务分解加每个任务的详情。可安全地重新运行以进行中途执行路线修正 |
| `/spek:execute` | 逐个实现任务。追加到 `execution.md`。在 Plan 中勾选复选框。可从任何未勾选处恢复 |
| `/spek:verify` | 目标后向验证。读取 Plan、执行日志和 `git diff`。写入 `## Verification`。如发现问题，提供运行 `/spek:execute` 修复、`/spek:plan` 修订或停止的选项。对源代码严格只读 |

### 便利（随时使用）

| 技能 | 功能 |
|-----|------|
| `/spek:commit` | 起草基于规格的 git 提交信息，总结自上次提交以来的工作（已完成任务、验证修复、路线修正），通过 AskUserQuestion 请求确认，然后提交。从不自动，从不修改，从不绕过钩子。尊重安装时选择的 `commit_style` |
| `/spek:status` | 显示所有功能及其状态、任务进度（如 3/5 完成）、最后修改日期的表格。高亮当前功能。严格只读 |
| `/spek:resume` | 专注的恢复助手 —— 显示当前功能状态、任务进度和最后执行日志条目，然后建议下一个正确命令。用于休息或上下文重置后返回。严格只读 |

## 设计决策对比

| 特性 | SpekLess | GSD | SpecKit |
|-----|----------|-----|---------|
| 功能文档 | 一个活的 `spec.md` | 分散（STATE、RESEARCH、PLAN、VERIFY）| 三个文件 |
| 层次结构 | 扁平功能列表 | 里程碑→阶段→任务 | 扁平 |
| 原子提交 | 从不强制 | 强制 | 不跟踪 |
| 任何步骤的干预 | ✅ | 状态机锁定 | 部分 |
| 现有代码的追溯采用 | `/spek:adopt` | ❌ | ❌ |
| 绿地 PRD 层 | `/spek:kickoff` + `project.md` | `PROJECT.md` + new-project | 部分 |
| 项目宪法 | `principles.md` | ❌ | `constitution.md` |
| 每个工作流步骤的子 Agent fan-out | 从不 | 重 | 从不 |
| Token 成本 | 最轻 | 最重 | 中等 |

## 安装与设置

SpekLess 是一组 Claude Code 技能和安装程序。克隆或下载此仓库，然后在任何想要使用 SpekLess 的项目中运行安装程序：

```bash
git clone https://github.com/balazsbohonyi/spek-less.git /path/to/spek-less
cd /path/to/your-project
/path/to/spek-less/install.sh
```

使用 `--defaults`（或 `-y`）跳过所有提示，非交互式接受默认值：

```bash
/path/to/spek-less/install.sh --defaults
```

安装程序会询问：
1. 斜杠命令命名空间（默认：`spek` —— 调用为 `/spek:plan`、`/spek:execute` 等）
2. 安装范围：per-project、global 或 both
3. 规格根目录（默认：`.specs/`）
4. `/spek:execute` 是否应建议提交（默认：no）
5. 子 Agent 委托阈值（默认：3 次读取）
6. 自由文本项目语言/框架提示
7. 是否创建起始 `principles.md`（默认：yes —— `/spek:kickoff` 会帮助填写）
8. `/spek:commit` 的提交信息风格 —— `plain`（默认）、`conventional` 或自定义自由文本规则

安装程序还会：
- 检测目录是否不是 git 仓库并提供运行 `git init`
- 复制模板到 `.specs/_templates/` 以便技能在运行时引用
- 写入 `CLAUDE.md`（如果不存在）的 `## SpekLess` 章节，使每个会话都有项目上下文

**幂等且对现有项目安全**：重新运行会保留你的功能、配置和原则，只修补缺失的内容。

## 工作流演示

### 演示 1：通过 `/spek:kickoff` 启动绿地项目

你正在启动新产品。有一个想法但没有代码。

```bash
cd /path/to/new/empty/repo
/path/to/spek-less/install.sh       # 对创建 principles.md 选择 yes
```

在 Claude Code 中：

```
/spek:kickoff "habit tracker for ADHD adults"
```

`/spek:kickoff` 运行扩展的澄清重对话。询问：
- 具体问题及受影响的人群
- 成功后的产品形态
- 主要用户（推动对模糊架构的反馈）
- 成功指标（领先指标，非虚荣指标）
- 范围进/出
- 约束（技术、业务、时间线）

写入 `.specs/project.md` 并提议初始功能集：

```
Initial Feature Set
- [ ] 001: Quick-capture for habit log
- [ ] 002: Daily check-in view
- [ ] 003: Streak tracking
- [ ] 004: Weekly summary email
```

最后询问是否为空规格文件夹搭建这些功能。如果是，`.specs/001_*`、`.specs/002_*` 等会创建最小 `spec.md` 文件。然后：

```
/spek:discuss 001
```

详细探索第一个功能，`project.md` 作为背景上下文。然后正常进行 `/spek:plan`、`/spek:execute`、`/spek:verify`。

### 演示 2：通过 `/spek:new` 进行持续功能工作

你有一个已安装 SpekLess 的现有项目。想添加新功能。

```
/spek:new "add dark mode toggle"
```

创建 `.specs/042_add-dark-mode-toggle/spec.md`（按顺序编号下一个）并立即返回。没有讨论，没有计划 —— 只有骨架。

```
/spek:discuss
```

运行澄清对话。写入 Context 和 Discussion。

```
/spek:plan
```

写入带任务分解的 Plan。对代码库不熟悉的部分，可能委托给 Explore 子 Agent，使主上下文保持精简。

```
/spek:execute
```

逐个实现任务。首次运行时创建 `execution.md`，在规格前元中存储 `starting_sha`，在进行时勾选复选框，并写入运行叙述到执行日志。你想何时提交就何时提交 —— 没有强制原子提交。

```
/spek:commit
```

可选，随时。从规格 + 执行日志尾部 + git diff 起草提交信息，展示给你，确认后提交。主题锚定到功能 ID（`001: Add dark mode toggle — tasks 1-3`）；正文列出自上次提交以来完成的任务或修复；页脚链接到规格。你可以接受草稿、粘贴修订或取消。

```
/spek:verify
```

读取 `git diff <starting_sha>..HEAD`、Plan 和执行日志。对非平凡功能委托给新鲜通用子 Agent 进行无偏见验证。写入 Verification 章节。如标记问题，通过 AskUserQuestion 提供三个选项：运行 `/spek:execute` 立即修复、`/spek:plan` 修订或停止。

### 演示 3：通过 `/spek:adopt` 追溯记录现有代码

你有未经 SpekLess 编写的代码，想要规格 —— 也许用于文档，也许作为重构前的验证基线。

```
/spek:adopt "the auth flow in src/auth/"
```

`/spek:adopt` 委托给 Explore 子 Agent 映射认证模块。然后写入追溯 `spec.md`：
- **Context** 从代码做什么推断（如不确定则标记为推断）
- **Discussion** 列出可见的设计决策
- **Plan** 所有任务预勾选（`[x]`）—— "这就是计划的样子"
- **starting_sha** = 当前 HEAD（空 diff，因为工作已完成）

然后：

```
/spek:verify
```

将其视为文档检查：读取每个任务的 Files/Approach 并确认代码匹配。任何差异都成为文档问题，而非 bug。

## 干预：中途改变方向

这是 SpekLess 与 GSD 最显著不同的地方。没有特殊的"干预模式"。你只需运行需要的任何技能。

**场景 —— 你正在执行中途，意识到方法错误：**

1. 中断 `/spek:execute`
2. 告诉对话需要什么改变
3. 运行 `/spek:plan` —— 读取 `execution.md`，确认已完成的工作，重写 Plan。未更改任务的复选框保留；已更改任务重置；新任务追加
4. 再次运行 `/spek:execute` —— 从第一个未勾选任务开始，追加 `Course correction` 条目到日志

**场景 —— 验证发现问题：**

1. `/spek:verify` 标记问题并以 AskUserQuestion 结束，提供三个选项
2. 选择 "run `/spek:execute` to fix"
3. `/spek:execute` 读取 Verification 章节，实现修复，追加到日志
4. 重新运行 `/spek:verify` 确认

**场景 —— 你想手动编辑章节：**

只需在编辑器中打开 `spec.md` 并编辑。技能每次运行都读取当前状态 —— 它们从不假设自己编写了当前内容。手动编辑是一等公民。

**场景 —— 上下文填满中途，功能未完成：**

`/spek:execute` 按构造可恢复 —— 追加式 `execution.md` + 未勾选 Plan 复选框就是所需的全部状态。当上下文变紧时：

1. 让当前任务干净完成（不要中途停止）
2. 让 Agent 追加 `## <timestamp> — Pausing for context reset` 条目到 `execution.md`，描述已完成和未完成的内容
3. 可选提交已有内容
4. **开始新会话**（`/clear` 或新终端）—— 只有会话边界才能真正缩小上下文；框架不能缩小自己的
5. 再次运行 `/spek:execute`。读取日志尾部，看到暂停条目，从第一个未勾选任务恢复

没有恢复命令，没有特殊标志，没有状态文件需要协调。文档即状态的特性使这 Just Work。

## 项目目录布局

```
<project-root>/
├── .specs/
│   ├── config.yaml                   # 每项目配置（安装程序写入）
│   ├── principles.md                 # 项目宪法（HOW we build）
│   ├── project.md                    # 产品愿景/PRD（WHAT & WHY）— 可选
│   ├── 001_auth-rewrite/
│   │   ├── spec.md
│   │   └── execution.md
│   ├── 002_token-storage/            # part_of: auth-rewrite（兄弟分解）
│   │   ├── spec.md
│   │   └── execution.md
│   └── 003_settings-ui/
│       ├── spec.md
│       └── execution.md
└── .claude/
    └── skills/
        └── spec/                     # 默认命名空间；安装时可配置
            ├── kickoff.md
            ├── new.md
            ├── adopt.md
            ├── discuss.md
            ├── plan.md
            ├── execute.md
            ├── verify.md
            ├── commit.md
            ├── status.md
            └── resume.md
```

## `principles.md` 宪法

每个 SpekLess 技能每次运行都读取 `.specs/principles.md`。这是你记录应塑造计划、指导执行、给验证具体检查内容的项目约定的地方。

保持原则**具体且可测试**。"写干净代码"没用。"所有公共函数必须至少有一个 `@example` 的 JSDoc"有用。

安装程序可以为你创建起始文件。编辑以反映你的实际约定。原则是粘性的 —— 它们适用于每个功能，不是一次性。

## SpekLess 如何保持精简

Token 效率不是副作用 —— 它是设计：

- **单 Agent 拓扑**：一个对话通过技能驱动一切。没有每个工作流步骤的冷启动子 Agent fan-out
- **子 Agent 仅作上下文防火墙**：当 `/spek:plan` 或 `/spek:adopt` 需要读取不熟悉的代码区域时，委托给 Explore 子 Agent 并接收提炼摘要。原始源代码从不进入主对话
- **章节范围读取**：技能使用 Grep 查找章节标题，然后用 `offset`/`limit` 只拉取所需章节。`/spek:plan` 不读取 Verification 章节。`/spek:verify` 不读取 Discussion 章节
- **文档即状态**：没有 STATE.md、没有 ROADMAP.md、没有锁文件。进度是 Plan 中的复选框集合；意图是最新章节重写所说的任何内容
- **基于 diff 的验证**：`/spek:verify` 首先读取 `git diff <starting_sha>..HEAD`，然后只在 diff 不清楚时针对特定文件。从不大批量读取源树
- **追加式执行日志**：旧条目从不重新读取，除非路线修正需要上下文。尾部通常足够

## 状态

**v1.0.0** —— 十个技能、安装程序、模板和两个完整工作示例。

Post-v1.0.0 候选（明确推迟到真实使用需求驱动）：
- `/spek:archive` 便利技能
- 日志变大时的执行日志压缩
- Git 钩子集成
- 契约测试 / OpenAPI 扩展
- 自定义 `spec-verifier` 子 Agent（当前使用通用）

## 结语

SpekLess 代表了一种务实的 AI 辅助开发工作流设计：用简单的文档模型和斜杠命令解决复杂的功能管理问题。它没有过度设计，没有状态机，只有清晰的文档即状态。对于正在使用 Claude Code 等 AI 编码工具的团队来说，这是一个轻量且高效的工作流选择。