# Tdd Workflow > Use this skill for developing software in TDD (Test-Driven Design). - Skill: `archibate/tdd-workflow` (Agent Skill) - Install (CLI): `npx skillmds@latest add archibate/tdd-workflow` - Raw SKILL.md: https://api.skillmd.com/api/skills/archibate/tdd-workflow/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: archibate (https://skillmd.com/u/archibate) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/archibate/tdd-workflow --- # TDD Workflow ## Overview A strict 7-step TDD cycle that produces high-quality, well-tested code. Each step must be **verified and confirmed** before proceeding. Status is only updated after real verification - never hallucinated. Core principle: **RED (failing test) -> GREEN (minimal implementation) -> REFACTOR**. --- ## Step 0 - Check Existing Progress At the start of each session, before doing anything else: - List `tdd-summary/` to check for existing step reports (e.g. `step-1.md`, `step-2.md`). - If reports exist, read them to understand prior context, then **resume from the next step**. --- ## Step 1 - Understand Intent - Explore the codebase for relevant context. - Derive functional requirements from the available information (user prompt + codebase). - If any requirement is ambiguous, document the assumption explicitly in `step-1.md` under an "Assumptions" section rather than asking for clarification. Write `tdd-summary/step-1.md`: ```markdown # Step 1 - Understand Intent ## Functional Requirements ### FR-1: <description> ### FR-2: <title> <description> ## Assumptions - <any ambiguous point and the assumption made> ``` --- ## Step 2 - Write Scenario Docs For each functional requirement, create a scenario document at `docs/scenario/<name>.md`: ```markdown # Scenario: <Title> - Given: <precondition> - When: <action> - Then: <expected outcome> ## Test Steps - Case 1 (happy path): <brief description> - Case 2 (edge case): <brief description> - Case N: ... ## Status - [x] Write scenario document - [ ] Write solid test according to document - [ ] Run test and watch it failing - [ ] Implement to make test pass - [ ] Run test and confirm it passed - [ ] Refactor implementation without breaking test - [ ] Run test and confirm still passing after refactor **IMPORTANT**: Only update above status when a step is confirmed complete. Do not hallucinate. ``` **Invariant**: Count of FR = count of scenario documents. Verify before continuing. Write `tdd-summary/step-2.md`: ```markdown # Step 2 - Write Scenario Docs ## Scenario Documents Created - FR-1: <title> - `docs/scenario/<name>.md` - ... ``` --- ## Step 3 - Write Failing Test (RED) For each scenario document: - Write tests at `tests/scenario/test_<name>.py` (or equivalent). - Each scenario must have **at least 2 test cases**. Add edge cases if missing. - All acceptance criteria from the scenario document must be covered. - Tests must **not** be empty or dummy. - Update scenario status: check `- [x] Write solid test according to document`. After writing, **run each test** and verify it fails: - **Expected failure** (e.g. feature not found, endpoint missing) - this is correct. - Update scenario status: check `- [x] Run test and watch it failing`. - **Unexpected failure** (e.g. import error, missing dependency) - fix the environment first. - **Test passes** - the feature is not implemented yet; there is no reason it should pass. Fix the test. **Invariant**: Count of scenario documents = count of test files. Verify before continuing. Write `tdd-summary/step-3.md`: ```markdown # Step 3 - Write Failing Test ## Failing Tests Created - FR-1: <title> - `docs/scenario/<name>.md` - `tests/scenario/test_<name>.py` - ... ``` --- ## Step 4 - Implement to Make Tests Pass (GREEN) For each failing test: - Write the **minimal production code** necessary to make the test pass. Nothing more. - Do not introduce changes unrelated to the current functional requirement. - Update scenario status: check `- [x] Implement to make test pass`. - Run the test. If it fails, fix the implementation and retry. - After confirming it passes, update scenario status: check `- [x] Run test and confirm it passed`. Write `tdd-summary/step-4.md`: ```markdown # Step 4 - Implement to Make Tests Pass ## Implementations Completed - FR-1: <title> - `docs/scenario/<name>.md` - Implementation in `<module>` - ... All tests now pass. Scenario documents updated. ``` --- ## Step 5 - Refactor for Maintainability For each scenario where tests now pass: - Improve readability, structure, and maintainability **without changing external behavior**. - Update scenario status: check `- [x] Refactor implementation without breaking test`. - Run the tests again after refactoring. - If tests fail: fix the refactoring. If impossible, **rollback to the pre-refactor version**. - After confirming tests still pass, update scenario status: check `- [x] Run test and confirm still passing after refactor`. Write `tdd-summary/step-5.md`: ```markdown # Step 5 - Refactor for Maintainability ## Refactorings Completed - FR-1: <title> - `docs/scenario/<name>.md` - <what was improved> - ... All tests still pass after refactoring. Scenario documents updated. ``` --- ## Step 6 - Regression Test Run the **complete test suite** (all tests, not just those added in this session): - If regression occurs in unrelated tests: - Analyze the failure and understand its impact on existing functionality. - Fix the implementation to restore all passing tests. - Re-run the complete suite until everything passes. **NEVER modify existing tests that are unrelated to the current functional requirements.** Write `tdd-summary/step-6.md`: ```markdown # Step 6 - Regression Test ## Regression Test Results - Complete test suite executed: `<command>` - All tests pass: Yes / No - If regression found: <brief description of fix applied> ``` --- ## Step 7 - Final Review Verify that **every scenario document has all status checkboxes checked**. Review: - Every FR has a corresponding scenario document and test file. - All tests pass and code is clean. Write `tdd-summary/step-7.md`: ```markdown # Step 7 - Final Review ## Summary - Functional requirements addressed: - FR-1: ... - Scenario documents: `docs/scenario/...` - Test files: `tests/scenario/...` - Implementation complete and all tests passing after refactoring. ## How to Test Run: `<test command>` ``` Finally, archive the summary folder: ```bash mv tdd-summary/ completed-tdd-archives/tdd-$(date +%Y%m%d-%H%M%S) ``` TDD workflow complete. --- ## Iron Rules - **Do not skip steps.** Each step must be verified before the next begins. - **Do not edit tests** during implementation or refactor steps, unless the test itself was obviously written incorrectly in Step 3. - **Do not hallucinate status.** Only check a status checkbox after real, confirmed verification. - **Keep counts equal.** FR count = scenario doc count = test file count at all times. - **Step gates**: If running interactively, present each step report and wait for confirmation before continuing. If running as a delegated subagent, proceed automatically through all steps. - **If changes are requested at any step**, loop back to the appropriate step and adjust all downstream artifacts accordingly.