features_and_tests

LLM-Assisted Development Framework

A framework for LLM-assisted software development with feature/bug-driven workflow, automatic test generation, and structured planning.

Based on the original Claude Code Project Template by ktnyt, adapted for feature-driven development with automatic test coverage.

Overview

This framework helps you work with LLMs (like Claude) to add features and fix bugs in existing codebases. It's designed for incremental development on working projects, not greenfield development.

Key Features

• Feature/Bug-Driven: Work from concrete requirements, not abstract sprints
• Automatic Test Generation: Achieve 85%+ coverage without manual test writing
• User-Controlled Workflow: Approval checkpoints at every major step
• No Auto-Commits: You maintain full control of your git history
• Existing Codebase Support: Designed to augment working projects

Quick Start

1. Copy this template to your project
2. Run /create-work-item to define a feature or bug fix
3. Run /implement-work-item to implement with automatic tests

Workflow

/create-work-item      →  Define feature or bug specification
/implement-work-item   →  Implement with automatic test generation
/arch-design          →  Design interfaces and architecture
/arch-review          →  Review architecture decisions
/audit-docs           →  Keep documentation accurate
/review-tests         →  Review test quality

Directory Structure

project/
├── CLAUDE.md                    # Principles, invariants, navigation
├── .coveragerc                  # Coverage configuration
├── docs/
│   ├── CAPABILITIES.md          # What the system does
│   ├── SCRATCHPAD.md            # Temporary context
│   ├── architecture/
│   │   ├── README.md            # Index, reading order
│   │   ├── PROCESS.md           # Development process
│   │   └── {feature}.md         # Design docs per subsystem
│   └── work-items/
│       ├── active/              # Current work items
│       ├── archive/             # Completed work items
│       ├── feature-TEMPLATE.md  # Feature specification template
│       └── bug-TEMPLATE.md      # Bug fix template
├── .claude/
│   ├── agents/                  # Worker definitions
│   │   ├── architect.md         # System designer
│   │   ├── implementer.md       # Code implementer
│   │   └── test-creator.md      # Automatic test generator
│   └── skills/                  # Process definitions
│       ├── create-work-item/    # Create work-item specs
│       ├── implement-work-item/ # Implement with auto-tests
│       ├── arch-design/         # Architecture design
│       ├── arch-review/         # Architecture review
│       ├── audit-docs/          # Documentation audit
│       ├── review-tests/        # Test review
│       ├── role-architect/      # Architecture mode
│       └── session/             # Session analysis
└── src/                         # Your source code
└── tests/                       # Generated and manual tests

Agents vs Skills

Type	Purpose	Location
Agents	Workers with specific expertise	.claude/agents/
Skills	Processes that orchestrate work	.claude/skills/

Agents do focused work (design, implement, test). Skills define workflows that may use agents.

Agent Roles

• Architect: Designs interfaces and makes architectural decisions
• Implementer: Writes code matching specifications exactly
• Test-Creator: Generates pytest tests to achieve coverage targets

Work Item Lifecycle

1. NEED IDENTIFIED
   └── User request, bug report, or enhancement idea

2. SPECIFICATION (/create-work-item)
   ├── Analyze existing codebase
   ├── Gather requirements
   └── Create docs/work-items/active/{name}.md

3. APPROVAL CHECKPOINT 1
   └── Review work-item specification

4. IMPLEMENTATION (/implement-work-item)
   ├── Analyze scope and present plan
   ├── APPROVAL CHECKPOINT 2: Review plan
   ├── Launch implementer agent
   ├── Write code per specification
   ├── Run pre-commit checks
   └── APPROVAL CHECKPOINT 3: Review code

5. TEST GENERATION (Automatic)
   ├── Run pytest with coverage
   ├── If coverage < 85%:
   │   ├── Present uncovered functions
   │   ├── APPROVAL CHECKPOINT 4: Approve test generation
   │   ├── Launch test-creator agent
   │   ├── Generate tests (max 3 cycles)
   │   └── Re-run coverage
   └── If still < 85% after 3 cycles:
       └── APPROVAL CHECKPOINT 5: Accept gap or continue

6. REVIEW
   ├── Launch reviewer agent
   ├── Mechanical audit (linting, coverage, dead code)
   ├── Spec-implementation comparison
   └── APPROVAL CHECKPOINT 6: Approve review findings

7. STAGE CHANGES
   ├── Stage all modified/created files
   ├── Present final summary
   └── User manually commits

8. ARCHIVE
   └── Move work-item to docs/work-items/archive/

Approval Checkpoints

Every /implement-work-item has 6 user approval checkpoints:

1. Analysis - Review code impact and plan
2. Implementation - Review code changes
3. Test Plan - Approve test generation strategy (if needed)
4. Coverage Gap - Decide on sub-85% coverage (if applicable)
5. Review - Approve review findings
6. Final - Commit or reset

You are never committed automatically. All changes are staged for your review.

Test Generation

Coverage Configuration

• Target: 85% minimum
• Framework: pytest (function-based only)
• Location: tests/test_*.py (flat structure)

What's Tested

• Business logic functions
• Error handling branches
• Input validation
• API endpoints
• Communication protocols
• Domain models with behavior

What's Excluded

• Third-party libraries
• Python standard library
• Dataclass definitions
• Constants and configuration
• Type hints and imports
• Simple property getters

See .coveragerc for complete exclusion rules.

Test Generation Rules

1. Follow existing patterns - Match style of existing tests
2. Fresh pytest patterns if none exist - Arrange-Act-Assert structure
3. Prefer integration tests - Test real behavior over excessive mocking
4. Minimal external dependencies - Mock only network/external services
5. Meaningful assertions - Every test must verify actual behavior
6. Max 3 generation cycles - Stop after 3 cycles if threshold not met

SCRATCHPAD Pattern

docs/SCRATCHPAD.md - Temporary context that doesn't fit into established docs.

• Create temporary in-between session context
• Write plans when not in plan mode

Important: Claude never writes to this file unless instructed. This is for the end user to manage.

Session Analysis

/session analyzes past Claude Code sessions so you can improve your skills and processes over time. Name sessions with /rename for easy lookup later.

Things you can ask:

• "List my recent sessions"
• "Find sessions where I used /implement-work-item"
• "Summarize that session — did it follow the spec?"
• "How much context did that session use?"
• "Show me the tool usage timeline"
• "Did the subagents work as expected?"
• "Why didn't that session work well? How can we improve it?"

Philosophy

Principles Are Guardrails

Without explicit principles, LLMs optimize locally and lose coherence across a project. Principles enable autonomous decision-making within bounds.

Good principles:

• Are specific enough to apply ("fail fast" not "be robust")
• Sometimes conflict (forces explicit tradeoffs)
• Include concrete examples and counter-examples

Three-Phase Workflow

Phase	Catches
Architect	Design issues, missing requirements
Implement	Execution errors
Review	Drift from spec, principle violations

Each phase uses a fresh context, preventing accumulated assumptions from hiding problems.

Code Is Truth

After implementation, code is the specification. Documentation:

• Links to code, doesn't duplicate it
• Captures rationale (why X over Y)
• Gets pruned after implementation

Specialized Agents

Each role loads minimal context and stays focused:

• Architect: Design only, no implementation
• Implementer: Execute spec, no design changes
• Test-Creator: Generate tests, no implementation changes
• Reviewer: Fresh eyes, loads spec not implementation context

User Control

This framework prioritizes user control:

• No automatic commits
• Approval at every checkpoint
• Clear presentation of changes
• Easy reset if needed

Customization Guide

See CUSTOMIZATION.md for detailed guidance on:

• Writing effective principles
• Structuring architecture docs
• Creating work-item specs
• Adding domain-specific agents
• Adjusting coverage targets

Coverage Configuration

Edit .coveragerc to customize:

• Coverage target (default: 85%)
• Source directories to measure
• Files/patterns to exclude
• Lines to exclude from coverage

Using CCLSP

CCLSP makes finding and reading code faster and more token efficient. It is mentioned throughout this framework. I highly recommend installing it. If you don't want to install it, then ask Claude to remove instructions on using it.

License

This is a template/framework. Use it however you want for your projects.

Acknowledgments

This framework is based on the Claude Code Project Template by ktnyt, significantly adapted for feature/bug-driven development with automatic test generation.