Test-Driven Development Workflow

This guide explains how to implement user stories using Test-Driven Development (TDD) with Claude Code and the lenne.Tech CLI.

Overview

The TDD workflow follows these principles:

1. Write Tests First: Define expected behavior before implementation
2. Minimal Implementation: Write only enough code to pass tests
3. Refactor: Improve code quality while keeping tests green
4. Review: Critically evaluate all generated code

Starting Claude Code

Navigate to your project directory and start Claude Code:

cd /path/to/your/project
claude

Or with the bypass permissions alias:

cd /path/to/your/project
c

Context Scope

Choose your starting directory based on the scope of work:

See Claude Code Common Workflows for more details.

Creating User Stories

Use the /create-story command to interactively create a user story:

/create-story

This command guides you through creating a well-structured user story that can be:

• Added to Linear as a ticket
• Directly implemented using TDD

Implementing User Stories

From Linear

1. Open the ticket in Linear
2. Copy the content as Markdown:
   • Context menu: ... > Copy > Copy content as Markdown
   • Or use keyboard shortcut: Cmd + Option + C (macOS)
3. In Claude Code, enter:

Implement the following user story with TDD:

[Paste the copied Markdown here]

Direct Implementation

For stories not in a ticket system:

Implement the following user story with TDD:

As a [user type]
I want [functionality]
So that [benefit]

Acceptance Criteria:
- [Criterion 1]
- [Criterion 2]
- [Criterion 3]

What to Expect

After execution, Claude Code will have:

• Created comprehensive test files in tests/stories/
• Implemented the feature to pass all tests
• Followed existing code patterns and conventions

Code Review Checklist

Review all changes for:

Correctness

• Code logic matches the user story requirements
• All acceptance criteria are satisfied
• Edge cases are properly handled

Security

• No injection vulnerabilities (SQL, command, XSS)
• Proper input validation and sanitization
• Authentication and authorization correctly implemented
• Sensitive data properly protected

Performance

• No N+1 query problems
• Appropriate use of indexes
• Efficient algorithms and data structures
• Proper caching where applicable

Code Quality

• Follows project coding standards
• Clear and descriptive naming
• Appropriate error handling
• No unnecessary complexity

Tests

• Tests are meaningful and comprehensive
• Tests cover edge cases
• Tests are maintainable and readable

Iterative Refinement

If issues are found during review, continue the conversation with Claude:

The implementation has the following issues:

1. [Describe issue 1]
2. [Describe issue 2]

Please fix these and update the tests accordingly.

Improving the CLI

When using commands and skills, you may identify improvements. Contribute these back to the community:

1. Make improvements in the lenne.Tech CLI Repository
2. Validate changes using the /skill-optimize command
3. Create a merge request

/skill-optimize

This command reviews and validates skill files against best practices before submission.

Best Practices

Do

• Review every line of generated code
• Run all tests locally before committing
• Ask Claude to explain unclear code
• Iterate on improvements incrementally
• Keep the conversation focused on one story

Don't

• Merge code you don't understand
• Skip security review for generated code
• Assume generated tests are comprehensive
• Ignore failing tests
• Implement multiple unrelated stories in one session

Troubleshooting

Tests Fail After Implementation

The tests are failing with the following errors:

[Paste error output]

Please analyze and fix the issues.

Generated Code Doesn't Follow Project Patterns

The generated code doesn't follow our project patterns.
We use [describe pattern].
Please refactor to match our conventions.

Need More Test Coverage

Please add additional tests for:
- [Edge case 1]
- [Edge case 2]
- [Error scenario]