Thema: Appendix C. Checklists and Templates
Schwierigkeitsgrad: Mittel
Geschätzte Lernzeit: 4-6 hours (2 hours theory, 2-4 hours practice)
Voraussetzungen: Basic understanding of SDD (Specification-Driven Development) methodology
Experience with version control systems (Git)
Familiarity with Markdown format
Understanding of project documentation structure (requirements.md, plan.md, validation.md)
Experience interacting with AI agents in development
Lernziele: Independently apply all Appendix C checklists at every stage of the feature lifecycle: from specification to merge request
Create complete merge requests and retrospectives using provided templates without skipping mandatory sections
Formulate minimal prompts for implementation review and replanning that ensure efficient AI agent operation
Organize a work session with an AI agent after the /clear command, following the new session checklist
Identify and prevent typical errors: secret leakage, unrelated refactorings, out-of-scope changes
Übersicht: Appendix C serves as an operational handbook for practical application of the SDD (Specification-Driven Development) methodology. Unlike theoretical chapters, this material is designed for immediate use "in the field" — during active project work. It contains six checklists covering the complete feature development cycle: from specification preparation through implementation to merge and retrospective, plus four ready-made templates for typical operations with an AI agent. The key value is prevention of typical errors that are costly when working with AI agents: context loss, secret leakage, scope creep, invalid results. The material is aimed at an intermediate level: it assumes the reader is already familiar with the basic structure of SDD documentation and ready to integrate checklists into daily practice.
Schlüsselkonzepte: Pre-specification checklist: Eight mandatory conditions that must be met before starting to write a specification. Checks clarity of goal, audience, work boundaries, stack constraints, verifiable results, roadmap phase, and availability of necessary resources. Critically important: attempting to create a specification without meeting these conditions leads to incomplete or inconsistent requirements that the AI agent will interpret unpredictably.
Pre-implementation checklist: Seven readiness control items before handing a task to the AI agent. Checks for presence and commit of three mandatory files (requirements.md, plan.md, validation.md), correct context transfer (file links instead of long chat history), clean branch, feature scope alignment with tech-stack.md, and absence of "Trojan" refactorings. Violation of this checklist is the primary cause of agent failures.
Pre-merge checklist: Seven quality criteria for final branch verification. Includes verification of mandatory facts from validation.md, explicit listing of failed and deferred facts with justification, review of new hooks and MCP servers, secret leakage check, CHANGELOG.md and roadmap update. This checklist is the last line of defense against poor-quality code entering the main branch.
Merge request template: Standardized MR/PR structure in Markdown format. Contains five mandatory sections: specification (with folder and phase), change list, verification facts with checkboxes, unverified/deferred facts, out-of-scope changes, and special instructions for the reviewer. Standardization ensures predictable review and reduces cognitive load.
SDD retrospective template: Five sections for systematic analysis of a completed feature: what the specification described correctly, what the agent inferred on its own, what the check caught, which facts were weak, what to transfer to QWEN.md or specs/, what to remove from the process. The retrospective closes the learning loop and accumulates organizational knowledge.
New session checklist after /clear: Six steps for restoring AI agent context after clearing chat history. Checks reading of base files (QWEN.md/AGENTS.md, mission.md, tech-stack.md), the needed feature folder, knowledge of forbidden files, expected verification commands, and stop conditions for research tasks. Without this checklist, the agent works "blindly".
Minimal prompt for implementation review: Standardized prompt for code verification by the agent. Structure: clear, read context, compare with three reference documents, output four categories of results (matches, discrepancies, unverified facts, out-of-scope changes), prohibition on modifying files. The minimalism of formulation prevents "creative" interpretation by the agent.
Minimal prompt for replanning: Standardized prompt for preparing the next roadmap phase. Structure: clear, read mission.md, tech-stack.md, roadmap.md, recent specifications and CHANGELOG.md, output list of necessary updates, prohibition on modifying files until approval. Ensures consistent project evolution.
Übungsaufgaben: Name: Specification audit using checklist
Problem: You are given an incomplete specification for the "PDF report export" feature. Check it against the pre-specification checklist. In the materials: goal described ("users want to save reports"), audience indicated ("all users"), work boundaries not defined, stack constraints not specified, one verifiable result ("file downloads"), roadmap phase not specified, requires integration with external API whose key is not available in local environment. Compile a list of blocking and non-blocking issues.
Lösung: 1. Blocking issues: absence of work boundaries (unclear what is in scope and what is not); absence of stack constraints (agent may choose incompatible technology); roadmap phase not specified (violates planning); requires external API with secret unavailable locally (blocks development and testing). 2. Non-blocking but requiring improvement: audience "all users" too vague — clarify roles; one verifiable result — add checks for content, format, error handling. 3. Actions: either obtain API access and usage instructions, or exclude integration from the feature, or create a mock for local development.
Komplexität: intermediate
Name: Forming a merge request using the template
Problem: Work on the "Address autocomplete" feature is complete. Known: specification folder specs/2024-03-15-address-autocomplete/, roadmap phase "Form UX Improvement", modified files src/components/AddressInput.tsx, src/hooks/useAddressAPI.ts, tests/AddressInput.test.tsx. Verified facts: npm run typecheck — passed, npm test — 2 out of 5 tests failed (known issue with external API rate limiting). New MCP server added for geocoding. CHANGELOG.md updated. Roadmap not updated as changes are minimal. Compile a complete MR using the template.
Lösung: ## Specification - Folder: specs/2024-03-15-address-autocomplete/ - Roadmap phase: Form UX Improvement ## What changed - Implemented AddressInput component with autocomplete - Added useAddressAPI hook for integration with geocoding service - Written unit tests for component ## Verification facts - [x] npm run typecheck - [ ] npm test (3/5 passed, 2 failed due to external API rate limiting) ## Unverified or deferred facts - Integration tests with real API: deferred, requires test account without rate limiting - Load testing: deferred until production keys received ## Out-of-scope changes - None ## What the reviewer should check especially carefully - New geocoding MCP server: check error handling and timeout - Correct hook operation during rapid input (debounce)
Komplexität: intermediate
Name: Diagnosing failure after /clear
Problem: A developer reports: after the /clear command, the AI agent started making changes to the .env file, although this file is explicitly forbidden from modification. The agent also ignored the existing project architecture and proposed an alternative technology stack. Analyze the situation using the new session checklist and compile a correct sequence of actions to restore operability.
Lösung: 1. Diagnosis: agent did not read QWEN.md/AGENTS.md (lacks knowledge of forbidden files); agent did not read tech-stack.md (does not know current stack); likely the agent also did not read the feature folder (works without context). 2. Correct sequence: execute /clear; command to read @QWEN.md; command to read @mission.md; command to read @tech-stack.md; command to read the needed feature folder; explicitly state: .env file must not be modified; explicitly state: technology stack is fixed in tech-stack.md; indicate expected verification commands; for research task — indicate stop condition. 3. Prevention: add explicit rule to QWEN.md "DO NOT modify .env and secret files" with example.
Komplexität: intermediate
Name: Detecting hidden refactoring
Problem: In the implementation plan for the "Email notifications" feature, the agent included an item "Refactoring authentication module to use new session storage". The current session storage is specified in tech-stack.md, and it does not conflict with the notifications feature. Analyze the situation using the pre-implementation checklist and determine the correct action.
Lösung: 1. Checklist analysis: item "no unrelated refactorings in plan" — NOT met. 2. Justification: authentication module refactoring has no causal connection to email notification sending; changing session storage is a separate feature with its own risks and validation requirements; mixing in one branch violates the principle of atomic changes. 3. Correct action: remove refactoring from plan.md of this feature; if refactoring is genuinely needed — create a separate specification with its own requirements.md, plan.md, validation.md; if refactoring blocks the feature — explicitly document this dependency and obtain approval for scope expansion. 4. Risks of ignoring: increased review volume, impact on unrelated functions, difficulty of rollback if problems occur.
Komplexität: intermediate
Fallstudien: Name: API key leak into specification: incident at a fintech startup team
Szenario: A team of 4 developers uses SDD for developing a payment processing microservice. A senior developer creates a specification for integration with the processor, including example requests with a real test API key for clarity. The specification is committed to the specs/ repository. The AI agent uses this key in code and logs during implementation. Code passes review and reaches staging.
Aufgabe: The test key ended up in three places: specs/ (specification), src/config/payment.ts (code), logs/debug-2024-01-15.log (logs). The key had access to the processor's test environment with real (though test) cards. The leak was only discovered during a security audit 3 weeks later. Potential damage: compromise of client test data, processor account blocking, reputational risks.
Lösung: Applied the pre-merge checklist, which was previously ignored due to haste. Implemented: automatic secret check via git-secrets in pre-commit hook; mandatory checklist item "secrets did not enter specifications, logs, and memory" with manual verification; specification template with placeholders instead of real keys (API_KEY_PLACEHOLDER); separate file secrets.template.md in .gitignore for local settings; retrospective with updating QWEN.md with rule "NEVER include real secrets in examples".
Ergebnis: Zero incidents in 8 months after implementation. MR check time increased by 2 minutes, but review time decreased by 15% due to standardization. Team discovered 2 more historical leaks during retrospective audit. Processor allocated a separate sandbox without real data.
Gewonnene Erkenntnisse: A checklist without an enforcement mechanism is useless — automatic checks or blocking code review are needed
Examples in specifications must use explicit placeholders, even if this reduces "clarity"
Retrospectives must record not only successes but also "weak facts" — they indicate systemic gaps
Rules from incidents must migrate to QWEN.md immediately, not "someday"
Verwandte Konzepte: Pre-merge checklist
SDD retrospective template
New session checklist after /clear
Name: Context recovery after failure: legacy system migration
Szenario: A consulting company is migrating a monolith to microservices with an AI agent. The project lasts 6 months, 47 specifications. At a critical moment, a new employee replaces the developer who does not know the project history. In the first session with the agent after /clear, it proposes using an ORM different from the one fixed in tech-stack.md, and starts rewriting existing migrations.
Aufgabe: The new developer gave the agent a "brief description" of the project instead of file links. The agent did not read tech-stack.md, did not learn about the prohibition on modifying existing migrations, did not understand architectural decisions from previous phases. Result: 3 hours of agent work went to waste, existing tests broke, the database in the local environment ended up in an inconsistent state.
Lösung: Strict adherence to the new session checklist after /clear: sequential reading of QWEN.md (with updated project rules), mission.md, tech-stack.md, current feature folder. Explicit indication of forbidden files: "migrations/2024-* must not be modified — they are applied in production". Using the minimal prompt for replanning to understand the current roadmap state. Implementing practice: every new participant undergoes a "trial session" with mentor observation.
Ergebnis: New developer onboarding time reduced from 5 days to 1.5 days. Created onboarding template in QWEN.md with list of "things every new participant must know". Lost agent work became a learning case for the team. Established rule: first request of any new session — always reading base files, no exceptions.
Gewonnene Erkenntnisse: "Brief description" does not replace structured files — the agent loses details and hallucinates
New session checklist is not a formality but a critically important context recovery mechanism
Forbidden files must be listed explicitly and specifically, not in general formulations
New participant onboarding must include AI agent practice under observation
Verwandte Konzepte: New session checklist after /clear
Minimal prompt for replanning
Minimal prompt for implementation review
Lerntipps: Create a physical or digital "memory map": print all checklists on one A4 sheet and keep in view during work — tactile presence reduces the likelihood of skipping items
Practice "reverse checklist": take completed MRs from your practice and check that they match the template — this reveals habitual omissions
Record typical errors in a personal "additional QWEN.md" — over time you will accumulate a list of project-specific additions to standard checklists
Use the technique "first request — always template": even if the situation seems unique, start with the minimal prompt and modify it — this prevents "creative" agent behavior
Conduct micro-retrospectives: 5 minutes after each feature, without waiting for a formal retrospective — record one thing the agent inferred on its own, and one that the specification described inaccurately
Pair learning: find a colleague and take turns playing "developer" and "checklist reviewer" roles — an outside perspective catches omissions you don't notice yourself
Adapt templates for your project: copy the MR template to your repository as .github/pull_request_template.md or equivalent — automatic template appearance eliminates the laziness of filling it out
Zusätzliche Ressourcen: Original Appendix C from SDD course: Source material on which this guide is based — use as a quick reference in field conditions
Templates for copying: Create in your project files: TEMPLATES/merge-request.md, TEMPLATES/retrospective.md, TEMPLATES/minimal-prompts.md with content from Appendix C
Secret checking tools: git-secrets (AWS Labs), truffleHog, GitGuardian — for automating the "secrets did not enter specifications" item
Checklist extensions: Markdown Checkbox in VS Code, GitHub Task Lists, Obsidian Tasks — for tracking item completion
Community QWEN.md examples: Search repositories tagged qwen-md or sdd-methodology for inspiration on context file structure
MCP server documentation: Resources on Model Context Protocol for understanding the "new MCP servers reviewed" item in the pre-MR checklist
Zusammenfassung: Appendix C is the operational brain of the SDD methodology, turning theoretical principles into concrete actions. Six checklists cover the complete feature lifecycle and protect against typical errors: incomplete specification, agent context loss, secret leakage, scope creep, inconsistent code. Four templates standardize communication and reduce cognitive load. The key principle: a checklist is executed completely or not at all — partial application is worse than absence, as it creates a false sense of security. Successful mastery of the material is measured not by knowledge of items but by automaticity of their application: checklists should become muscle memory, and templates — the default way of working. Regular retrospectives close the learning loop, transforming individual experience into organizational knowledge.