atxtechbro / atxtechbro/dotfiles

Add `.claude/commands/principle-driven-tdd` command for AI-guided test-driven development

Open Beginner friendly
#720 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Shell
Stars
27
Forks
2
PR merge metrics
No merged PRs in 30d

Description

## Summary
Create a new Claude command that guides AI toward test-driven development through principles rather than prescriptive steps, allowing the AI to discover optimal workflows while maintaining TDD best practices.

## Motivation
Current TDD workflows often prescribe exact steps (write tests → run tests → write code → iterate), which can be rigid and may not adapt well to different contexts. By establishing principles instead of methods, we enable AI to:
- Discover the most appropriate workflow for each situation
- Innovate on traditional TDD when beneficial
- Maintain flexibility while ensuring quality
- Learn and adapt rather than follow rote procedures

## Detailed Design

### Command Structure
```
.claude/commands/principle-driven-tdd
```

### Core Principles to Embed

1. **Principle of Verifiable Intent**
- *Definition*: "Before creating any solution, establish clear, measurable criteria for success that can be independently verified."
- *Purpose*: Naturally guides toward creating tests without explicitly requiring them

2. **Principle of Incremental Certainty**
- *Definition*: "Commit to permanent record only what has been verified to work correctly. Each commitment should represent a stable, known-good state."
- *Purpose*: Encourages commit discipline without prescribing when to commit

3. **Principle of Failure-First Learning**
- *Definition*: "Understand what failure looks like before attempting success. Confirm that your success criteria can actually detect failure."
- *Purpose*: Leads to running tests before implementation naturally

4. **Principle of Isolated Iteration**
- *Definition*: "When pursuing a target outcome, adjust only the implementation while keeping success criteria constant. Iterate until alignment is achieved."
- *Purpose*: Creates the natural test-code-iterate loop

5. **Principle of Progressive Refinement**
- *Definition*: "Complex solutions emerge from simple, verified components. Build confidence through small, validated steps rather than large leaps."
- *Purpose*: Encourages incremental development

### Command Template
```yaml
name: principle-driven-tdd
description: Guide development using TDD principles rather than prescriptive steps
parameters:
- name: feature
description: The feature or change to implement
required: true
- name: context
description: Additional context about the codebase or requirements
required: false

prompt: |
You are developing software following these core principles:

1. **Verifiable Intent**: Before building anything, establish clear, measurable
criteria for what success looks like. These criteria should be concrete enough
that anyone could independently verify whether they're met.

2. **Incremental Certainty**: Only commit changes that have been verified to work.
Each saved state should be stable and functional.

3. **Failure-First Learning**: Understand how to detect failure before attempting
implementation. Verify your detection methods work by confirming they can
identify when criteria aren't met.

4. **Isolated Iteration**: When working toward a goal, keep your success criteria
stable while adjusting only your implementation. Continue refining until your
implementation satisfies all criteria.

5. **Progressive Refinement**: Build complex functionality through small, verified
steps. Each step should add value while maintaining all previous functionality.

Your task is to implement: {feature}

{context}

Approach this systematically, ensuring each principle guides your workflow.
Consider how these principles interact and reinforce each other as you work.
```

### Expected Behaviors
When following these principles, the AI should naturally:
- Create tests or other verification methods first
- Ensure tests can fail before implementing
- Commit verified work incrementally
- Iterate on implementation without changing tests
- Build features progressively

However, the AI maintains flexibility to:
- Choose appropriate testing strategies (unit, integration, E2E)
- Determine optimal commit points
- Adapt the workflow to the specific context
- Innovate on traditional TDD when beneficial

## Implementation Notes

### Success Metrics
- AI consistently produces verifiable code
- Development follows incremental, stable progression
- Quality remains high without prescriptive constraints
- AI can explain its workflow choices in terms of principles

### Extensibility
The principle-based approach allows for:
- Adding new principles as needed
- Customizing principles for specific domains
- Combining with other development methodologies
- Learning from AI's workflow innovations

## Example Usage

```bash
claude run .claude/commands/principle-driven-tdd \
--feature "Add user authentication with JWT tokens" \
--context "Express.js API with PostgreSQL database"
```

## Benefits Over Prescriptive Methods

1. **Adaptability**: AI can adjust approach based on context
2. **Innovation**: Allows discovering better workflows
3. **Understanding**: AI comprehends why, not just what
4. **Resilience**: Principles remain valid even as tools change
5. **Teaching**: AI can explain decisions in terms of principles

## Related Commands
- `.claude/commands/tdd` (traditional prescriptive TDD)
- `.claude/commands/verify-changes` (verification-focused workflow)
- `.claude/commands/iterative-development` (iteration-focused workflow)

## References
- Harrington Emerson's distinction between principles and methods
- Test-Driven Development best practices
- Agile principles over prescriptive processes
- AI-assisted development patterns

Contributor guide

No contributing guide indexed for this repository

Research direction

Create .claude/commands/principle-driven-tdd using the command template and five principles in the issue as the specification. First compare .claude/commands/tdd, verify-changes, and iterative-development, then check the example claude run invocation. Done when the command accepts the required feature and optional context and supports the listed expected behaviors without prescribing a fixed workflow.

Written by the indexing model from the issue text.

Assessment

Tech stack
shell
Domain
cli, tooling
Issue type
Feature
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.