129 lines
3.9 KiB
Markdown
129 lines
3.9 KiB
Markdown
# Detail-MD Template
|
|
|
|
**Jede Task-Detail-MD MUSS dieser Struktur folgen.** Subagents die Detail-MDs erstellen halten sich strikt daran.
|
|
|
|
```markdown
|
|
# <Task-Title>
|
|
|
|
**Status:** pending | in_progress | blocked | completed | skipped
|
|
**Task-ID:** #<n> (matches TaskCreate ID in conversation history)
|
|
**Phase:** <01-11>
|
|
**Estimated Effort:** <e.g. 3-5 days>
|
|
**Owner:** unassigned (wird vom ausführenden Agent gesetzt)
|
|
|
|
## Problem
|
|
|
|
Was ist das Problem? Warum müssen wir es lösen? Welche Codestellen sind betroffen (file:line)?
|
|
|
|
## Depends on
|
|
|
|
- `<phase>/<task-file>.md` — Begründung warum dieser Task vorher fertig sein muss
|
|
- (weiter wenn nötig)
|
|
|
|
## Blocks
|
|
|
|
- `<phase>/<task-file>.md` — was dadurch blockiert ist
|
|
|
|
## Approach
|
|
|
|
Ausgewählter Approach mit Begründung (warum nicht die Alternativen). Wenn ein Subagent das implementiert, soll er nicht erneut Architektur-Entscheidungen treffen müssen.
|
|
|
|
## Implementation Steps
|
|
|
|
Atomare, nummerierte Schritte. Jeder Schritt soll mit einem atomic commit endbar sein.
|
|
|
|
1. **Step Title** — was genau passiert
|
|
- Files: `<file-path>` (was wird touched)
|
|
- Commit: `<phase>/<task>: <kurze msg>`
|
|
2. **Step Title** — ...
|
|
|
|
## Test Requirements
|
|
|
|
Konkrete Test-Spec:
|
|
|
|
- **Unit-Tests:** welche Funktionen/Klassen müssen getestet sein, welche Cases
|
|
- **Integration-Tests:** welche End-to-End-Flows
|
|
- **E2E-Tests (Playwright):** wenn UI involviert, welche User-Flows
|
|
- **Coverage-Target:** % für den Task-Scope
|
|
- **Test-Files:** wo werden sie liegen
|
|
|
|
Konkrete Anweisung: **NICHT als completed markieren bevor alle Tests grün sind.**
|
|
|
|
## Acceptance Criteria
|
|
|
|
Checkliste was Pflicht ist:
|
|
|
|
- [ ] <konkretes verifizierbares Kriterium>
|
|
- [ ] <konkretes verifizierbares Kriterium>
|
|
- [ ] Tests grün (lint, typecheck, unit, integration, e2e wenn anwendbar)
|
|
- [ ] Doku-File angelegt unter `docs/<feature>.md` (wenn im Task gefordert)
|
|
- [ ] Detail-MD Progress Log aktualisiert
|
|
- [ ] PROGRESS.md Status auf `completed`
|
|
|
|
## Rollback Strategy
|
|
|
|
Wenn dieser Task in Production Probleme verursacht — wie roll-backen?
|
|
|
|
- Welche Commits revert-bar
|
|
- DB-Migrations down?
|
|
- Feature-Flag um Funktion zu deaktivieren?
|
|
|
|
## Security Notes
|
|
|
|
Was sind die Security-relevanten Aspekte? (Auch wenn der Security-Track separat läuft, manche Tasks haben inhärente Sicherheits-Considerations die mitgedacht werden müssen.)
|
|
|
|
## Subagent Recommendations
|
|
|
|
Welche Subagents nutze ich für welchen Schritt?
|
|
|
|
- **Planning:** `Plan`-Subagent mit Task-Spec als Input
|
|
- **Research (wenn nötig):** `Explore` oder `general-purpose` mit konkretem Such-Auftrag
|
|
- **Implementation:** `general-purpose` mit klarem Brief, max 1 logischer Schritt pro Subagent
|
|
- **Tests:** separater `general-purpose`-Subagent für Test-Schreiben
|
|
- **Verification:** `gsd-verifier` oder `general-purpose` für Acceptance-Criteria-Check
|
|
- **Code-Review:** `gsd-code-reviewer` nach Task-Completion
|
|
|
|
## Staging-Deployment-Steps
|
|
|
|
Wenn der Task externe Services oder Production-ähnliche Validation braucht:
|
|
|
|
1. Branch `agent/<phase>-<task-name>` pushen
|
|
2. Coolify-Auto-Deploy auf staging-instance triggert
|
|
3. Smoke-Test-Commands die manuell auf Staging laufen sollen
|
|
4. Falls neuer Container/Service: docker-compose-snippet für Staging-Hetzner-Server
|
|
|
|
## Deviations from Plan
|
|
|
|
(Wird vom ausführenden Agent während Implementation gefüllt, falls Abweichungen)
|
|
|
|
## Progress Log
|
|
|
|
(Wird vom ausführenden Agent nach jedem commit gefüllt)
|
|
|
|
- YYYY-MM-DD HH:MM — `<commit-sha-short>` — Kurzbeschreibung
|
|
- ...
|
|
|
|
## Lessons Learned
|
|
|
|
(Optional, am Ende des Tasks für nachfolgende Tasks)
|
|
```
|
|
|
|
## Section-Reihenfolge ist verbindlich
|
|
|
|
Beim Lesen erwarten ausführende Agents diese Reihenfolge:
|
|
1. Frontmatter (Status, Task-ID, Phase, Estimated Effort, Owner)
|
|
2. Problem
|
|
3. Depends on
|
|
4. Blocks
|
|
5. Approach
|
|
6. Implementation Steps
|
|
7. Test Requirements
|
|
8. Acceptance Criteria
|
|
9. Rollback Strategy
|
|
10. Security Notes
|
|
11. Subagent Recommendations
|
|
12. Staging-Deployment-Steps
|
|
13. Deviations from Plan
|
|
14. Progress Log
|
|
15. Lessons Learned (optional)
|