---
id: gh-spec
name: "spec"
url: https://skills.yangsir.net/skill/gh-spec
author: juliusbrussee
domain: ai-software-architecture-engineering
tags: ["spec", "architecture", "engineering", "documentation", "workflow"]
install_count: 2700
rating: 4.40 (120 reviews)
github: https://github.com/juliusbrussee/cavekit/tree/main/skills/spec
---

# spec

> `spec` 技能是一个强大的技术规范管理工具，它能根据用户想法生成新规范，从现有代码中提炼规范，通过回溯机制自动处理bug并更新相关规范，或对现有规范进行精准修订。该 Skill 确保技术规范与代码库保持同步，显著提升软件架构的清晰度与工程实践效率。

**Stats**: 2,700 installs · 4.4/5 (120 reviews)

## Before / After 对比

### 规范更新效率提升

**Before**:

工程师手动分析代码、定位问题并更新技术规范，耗时且易出错，导致规范与实际代码脱节，影响开发效率。

**After**:

利用AI Skill自动分析bug描述和代码，快速定位并更新SPEC.md中的相关部分，显著提升规范更新效率和准确性。

| Metric | Before | After | Change |
|---|---|---|---|
| 规范更新时长 | 60分钟 | 10分钟 | -83% |

## Readme

# spec — spec mutator

Read `FORMAT.md` at repo root if not already loaded. Caveman skill applies to all writes here.

## DISPATCH

Inspect user request and project state:

1. No `SPEC.md` at repo root AND args describe idea → **NEW**
2. No `SPEC.md` AND `from-code` in args → **DISTILL**
3. `SPEC.md` exists AND args start `bug:` → **BACKPROP**
4. `SPEC.md` exists AND args start `amend` → **AMEND**
5. `SPEC.md` exists, no args → ask user which mode

## NEW — idea → spec

Input: user idea.

Steps:
1. Extract goal (1 line, caveman). → §G.
2. List constraints user stated or implied. → §C.
3. List external surfaces user named. → §I.
4. Propose initial invariants. → §V (numbered V1…).
5. Break goal into ordered tasks. → §T pipe table, all status `.`, ids T1…
6. §B section with header row only (`id|date|cause|fix`).

Write to `SPEC.md`. Show user full file. Ask: "spec OK? suggest edits or invoke build."

## DISTILL — code → spec

Walk repo. Produce §G (infer from README/package.json/main entry), §C (infer from stack), §I (enumerate public APIs/CLIs/configs), §V (derive from tests and assertions), §T (one task per known TODO or missing test), §B (empty).

Caveman everywhere. Flag uncertain items with `?` in text so user can confirm.

## BACKPROP — bug → §B + §V

Input: `bug: <description>`.

Steps:
1. Parse bug description.
2. Find root cause (read relevant code).
3. Decide: would a new invariant catch recurrence? If yes → draft `V<next>`.
4. Append §B row: `B<next>|<date>|<cause>|V<N>`.
5. Append new invariant to §V.
6. If fix also changes behavior → add/update §T rows.
7. Show diff. Apply only on user OK.

Rule: every bug gets a §B entry. Invariant optional but preferred.

## AMEND — targeted edit

Input: `amend §V.3` or `amend §T` etc.

Read that section. Show current. Ask user what changes. Write. Show diff.

Never silently rewrite sections user did not name.

## OUTPUT RULES

- Caveman format per `FORMAT.md`.
- Preserve identifiers, paths, code verbatim.
- Numbering monotonic — never reuse §V.N or §B.N.
- §T row `cites` column ! list §V/§I deps: `T5|.|impl auth mw|V2,I.api`.

## NON-GOALS

- No sub-agents. Main thread writes.
- No dashboards, no logs, no state files beyond SPEC.md itself.
- No auto-build after spec. User invokes build explicitly.


---
*Source: https://skills.yangsir.net/skill/gh-spec*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-spec/markdown*