Lesson #1483

ID

1483

Author

ai

Agent

agent-claude

Reviewed

✓ Yes

Source authority

75 / 100

Source

Alle Agenten (claude/codex/or/gemini/cursor) müssen Spec-Driven-Development einhalten: erst Spec/Plan-Dokument, dann TDD-Tasks, dann Code

Source issue

—

Created at

2026-05-12T14:06:41.352535+00:00

Valid until

—

Deprecated at

—

Supersedes

—

Obsidian path

/root/.claude/projects/-nvmetank1-projects/memory/feedback_spec_driven_development.md

Obsidian hash

b81b672438c2b72127781659eaba72c5

Tags

claude-memory,feedback

Content

**Rule:** Jede non-trivial-Task (>30 Zeilen oder cross-file) MUSS einen Spec + Plan in `docs/superpowers/{specs,plans}/` haben BEVOR Code geschrieben wird.

**Why:** User-Direktive 2026-05-12: "schauen dass agents immer Spec-Driven Development (SDD) einhalten". Ohne SDD: Agenten implementieren Lösungen die das eigentliche Problem nicht treffen, Refactors sind ad-hoc, Test-Coverage zufällig.

**Vorlage (proven pattern aus bugtest-stack):**

```
docs/
  superpowers/
    specs/
      2026-05-12-feature-X-design.md     ← WHAT (Requirements, Scope, Constraints, APIs)
    plans/
      2026-05-12-feature-X-phase1.md     ← HOW (TDD-Tasks: failing-test → code → commit)
```

## SDD-Checkliste pro Agent-Task

**Pre-code (Spec phase):**
- [ ] Spec-Dokument in `docs/superpowers/specs/YYYY-MM-DD-<slug>-design.md` existiert
- [ ] Spec enthält: Goal, Non-Goals, API/Schema/UI-contracts, Acceptance criteria, Open Questions
- [ ] User-direktive oder Issue-Body referenziert die Spec

**Plan phase:**
- [ ] Plan-Dokument in `docs/superpowers/plans/YYYY-MM-DD-<slug>-phase1.md` existiert
- [ ] Tasks nummeriert, jeder mit: failing-test-vorschlag + minimal-code-vorschlag + commit-message-vorschlag
- [ ] Akzeptanz pro Task explizit (pytest-ausgabe, curl-output, screenshot)

**Code phase (per Task):**
- [ ] Failing-Test zuerst (red)
- [ ] Minimal Code (green)
- [ ] Refactor optional (blue)
- [ ] Commit mit Plan-Reference: `feat(scope): <one-line> — plan §3.2`

## Wann SDD übersprungen werden DARF

- Single-line bugfix mit obvious-fix (TypoX, falsche Import)
- Mechanical refactor (rename, search-replace) — keine Logik-Änderung
- Hotfix in Production-broken-state (dann SDD post-mortem within 24h)
- Stub/Skeleton-Creation (mkdir + leere __init__.py)

## Wo Spec dispatchet wird

Im Gitea-Issue-Body MUSS stehen:

```
## Spec
docs/superpowers/specs/2026-05-12-feature-X-design.md

## Plan
docs/superpowers/plans/2026-05-12-feature-X-phase1.md  §3 (oder §1-§5)
```

Wenn die Spec-Files noch nicht existieren: dispatch-Comment sagt explizit
`@agent-claude` bitte Spec + Plan zuerst, dann re-dispatch.

## Handler-Enforcement

`/usr/local/lib/agent-handler-common.sh` `fetch_issue_context()` checkt
ob `docs/superpowers/specs/` oder `## Spec`/`## Plan` im Issue-Body —
wenn nicht, prepend Warning an den Prompt: 
"⚠️ NO SPEC REFERENCED — start by writing one (siehe Memory feedback_spec_driven_development)".

## Bestehende guten Beispiele

- `bugtest-stack/docs/superpowers/specs/2026-05-12-bugtest-stack-design.md` + matching plan
- `bugtest-stack/docs/superpowers/plans/2026-05-12-bugtest-stack-phase1.md` (18 nummerierte TDD-Tasks)

## Anti-pattern (vermeiden)

- "@agent-codex bitte fix das" ohne Spec-link
- Sprung in Code ohne plan-Datei
- "tests/conftest.py" creation ohne Test-First-Erklärung was getestet wird

## Tooling

```bash
# Spec-Template erzeugen:
mkdir -p docs/superpowers/specs docs/superpowers/plans
cat > docs/superpowers/specs/$(date +%Y-%m-%d)-<slug>-design.md <<EOF
# <Feature Name> — Spec

## Goal
<one paragraph>

## Non-Goals
- ...

## API / Schema / UI contracts
- ...

## Acceptance criteria
- [ ] ...

## Open Questions
- ...
EOF
```

Plan-Template ähnlich, mit Tasks nummeriert + TDD-Steps.