Intermediate Scenarios

These scenarios build on the prompting and workflow skills from Sessions 1-2: specific prompts, @file references, and iterating on responses. They cover TDD, code review, refactoring, and documentation workflows applied to your own codebase.

Each scenario builds a habit you will use daily. Work through them at your own pace.

---

Test-Driven Development

Time: 15 min | Technique: TDD workflow

The situation: You need to add new functionality to an existing service or module in your project. Instead of writing the implementation first and testing later, you want to practice the red-green-refactor cycle with Claude as your pair programming partner.

What to do:

1. Identify a class or module in your project that needs new functionality. Tell Claude what the new behavior should be: I need to add [describe the feature] to @path/to/your-module. Write a failing test that captures this behavior. Do not write any implementation yet.
2. Review the test to make sure it captures your intent. Then ask Claude: Now write the minimal implementation to make this test pass without breaking any existing tests.
3. Repeat steps 1-2 for two more behaviors. After all tests pass, ask Claude: All tests are passing. Review the implementation and suggest refactoring opportunities. Apply them while keeping all tests green.

Success looks like: You have at least three new tests and a clean implementation. You have experienced the red-green-refactor cycle with Claude writing tests first, implementing second, and refactoring third.

---

Code Review

Time: 15 min | Technique: Code review workflow

The situation: You have a recent pull request, a module you suspect has quality issues, or a file that has grown complex over time. You want Claude to perform a structured review covering security, performance, correctness, and readability — the same categories you would check in a manual review, but faster.

What to do:

1. Point Claude at the code: Read @path/to/your-file and review it as if this were a pull request. Identify all bugs, security vulnerabilities, performance problems, and code quality issues. Prioritize them by severity.
2. Ask for a focused pass on the category you care most about: Now review this file specifically for security vulnerabilities. Check for injection attacks, authentication gaps, sensitive data exposure, and input validation problems.
3. Have Claude fix the critical issues: Fix the top 3 most critical issues you found. Show me the changes before I accept them.

Success looks like: You have a prioritized list of issues in your code, organized by category and severity. At least one critical issue has been fixed and reviewed.

---

Refactoring Legacy Code

Time: 30 min | Technique: Refactoring workflow

The situation: You have a file in your project that works but is painful to maintain — long methods, deep nesting, duplicated logic, or too many responsibilities in one class. You want to refactor it step by step with Claude, keeping existing behavior intact by writing tests first.

What to do:

1. Point Claude at the file: Read @path/to/your-legacy-file and explain what it does. Identify all the code smells and rank them by how much they hurt maintainability.
2. Write safety nets before changing anything: Before we refactor, write tests that capture the current behavior of this file. We need these tests to pass before and after refactoring so we know we did not break anything.
3. Refactor one smell at a time. Start with the highest-impact one: The [method name] method is too long. Extract smaller, well-named methods from it. Run the tests after each extraction to confirm nothing broke.
4. Once extraction is done, tackle structure: The [describe the conditional or duplication] should be simplified. Apply [Extract Class / Replace Conditional with Polymorphism / another pattern]. Show me the diff before I accept.

Success looks like: The file is split into focused, well-named pieces. All original behavior is preserved (tests pass). You have applied at least two refactoring patterns and reviewed each change before accepting it.

---

Documentation Generation

Time: 15 min | Technique: Explore-Plan-Code-Commit

The situation: You have a service, library, or module that works but has little or no documentation. Other engineers who integrate with it have to read the source code or ask you directly. You want Claude to generate accurate documentation — and then validate it against the actual code.

What to do:

1. Ask Claude to generate docs from source: Generate API documentation for @path/to/your-service. For each public method or endpoint, document: what it does, parameters with types, return values, error cases, and an example. Include a header noting this documentation was AI-generated.
2. Validate the output: Now validate the documentation you just generated against the actual source code. For each documented method or endpoint, verify the parameter types, return types, and error cases match the code. Create a checklist with PASS/FAIL for each item.
3. Fix any discrepancies: Based on the validation, update the documentation to fix the issues you found. Also cross-reference against any test files to find edge cases that should be documented.

Success looks like: You have accurate, validated documentation for a real service in your project. You have practiced the generate-then-validate pattern and understand that the validation step is where most of the value lies.