claude-dev-framework

A reusable framework for AI-assisted software development with Claude. It provides a structured workflow, reusable skills (prompt templates), and coding standards that can be initialized in any project.

The framework enforces a design-first, TDD-driven approach with 12 steps — from discussion through implementation to session wrap-up — ensuring consistent code quality and architectural coherence across AI-assisted development sessions.

---

Installation

Four installation methods are available. Choose the one that fits your setup.

Option 1 — One-liner

Unix/macOS:

curl -sL https://raw.githubusercontent.com/YOUR_USERNAME/claude-dev-framework/main/init.sh | bash

Windows (PowerShell):

powershell -c "irm https://raw.githubusercontent.com/YOUR_USERNAME/claude-dev-framework/main/init.cmd -OutFile $env:TEMP\cdf-init.cmd; cmd /c $env:TEMP\cdf-init.cmd"

This downloads the framework, runs the interactive setup, and generates the .dev/ structure in your current directory.

Option 2 — npx (requires Node.js)

npx claude-dev-framework

Same interactive setup, no permanent installation required.

Option 3 — Clone and run

git clone https://github.com/YOUR_USERNAME/claude-dev-framework.git
cd claude-dev-framework
./init.sh --target /path/to/your/project

For Windows (without WSL):

git clone https://github.com/YOUR_USERNAME/claude-dev-framework.git
cd claude-dev-framework
init.cmd --target C:\path\to\your\project

Option 4 — GitHub template (new projects only)

Click "Use this template" on the GitHub repository page to create a new repository with the framework included. Then run init.sh (or init.cmd) to customize it for your project.

---

What gets generated

After running the init script, a .dev/ directory is created in your project with the following structure:

.dev/
├── CONTEXT.md # Entry point for Claude — read at session start
├── WORKFLOW.md # 12-step development workflow
├── config.yml # Record of your init choices
├── standards/
│ └── <LANGUAGE>_STANDARDS.md # Coding standards for your language
├── design/
│ ├── ARCHITECTURE.md # Design decisions and rationale
│ └── INVARIANTS.md # Structural invariants
├── backlog/
│ └── BACKLOG.md # Task tracking
└── skills/
├── static-analysis/SKILL.md # Post-implementation code review
├── design-review/SKILL.md # Pre-implementation design validation
├── test-coverage-review/SKILL.md # Test suite completeness check
├── api-consistency-check/SKILL.md # API naming and convention review
├── architecture-drift-check/SKILL.md # Implementation vs. design check
├── update-backlog/SKILL.md # End-of-session backlog update
├── update-readme/SKILL.md # Documentation update
├── new-class/SKILL.md # New class scaffolding procedure
├── refactor-class/SKILL.md # Refactoring checklist
├── jml-design/SKILL.md # (Java + DbC only)
├── jml-test-generation/SKILL.md # (Java + DbC only)
├── jml-conformance-check/SKILL.md # (Java + DbC only)
└── jml-completeness-check/SKILL.md # (Java + DbC only)

The JML skills are only included if you enable Design by Contract with Java. The DbC workflow (14 steps) is used regardless of language when DbC is enabled.

---

Configuration

Interactive mode

The init script asks the following questions:

Question	Values	Default
Project name	any string	directory name
Language	java, python, typescript	—
Author name	any string	—
License	MIT, LGPL-3.0, Apache-2.0, none	MIT
Java package	e.g. com.example.mylib	— (Java only)
Design by Contract	y / N	N

Config file mode

You can skip the interactive prompts by passing a YAML config file:

./init.sh --config config.yml

See config.example.yml for the full format:

project_name: my-librarylanguage: javaauthor: Your Nameyear: 2026license: MITpackage: com.example.mylibdbc: false

The init script also generates a config.yml inside .dev/ as a record of the choices made.

---

The workflow

The framework defines a development workflow in two variants:

Standard workflow (10 steps)

Step	Description	Model
1. Discussion	Design the class before coding	Opus
2. Design review	Validate architecture	Sonnet
3. Architecture docs	Update ARCHITECTURE.md, INVARIANTS.md	Sonnet
4. Backlog	Update BACKLOG.md	Haiku
5. Tests (TDD)	Interface + black-box tests	Sonnet
6. Implementation	Make tests pass	Sonnet
7. White-box tests	Internal edge cases	Sonnet
8. Static analysis	Structured code review	Sonnet
9. Test coverage	Verify completeness	Sonnet
10. Documentation + wrap-up	README, backlog update	Sonnet/Haiku

Design by Contract workflow (14 steps)

Adds formal contracts before implementation and verification after:

Step	Description	Model
1. Discussion	Design the class before coding	Opus
2. Stub + contracts	Skeleton with formal contracts	Sonnet
3. Design review	Validate architecture	Sonnet
4. Architecture docs	Update ARCHITECTURE.md, INVARIANTS.md	Sonnet
5. Backlog	Update BACKLOG.md	Haiku
6. Tests (TDD)	Interface + black-box tests (derived from contracts)	Sonnet
7. Implementation	Make tests pass	Sonnet
8. White-box tests	Internal edge cases	Sonnet
9. Static analysis	Structured code review	Sonnet
10. Contract conformance	Verify code matches contracts	Sonnet
11. Contract completeness	Verify contracts cover all code	Sonnet
12. Test coverage	Verify completeness	Sonnet
13. Documentation	README, API docs	Sonnet/Haiku
14. Session wrap-up	Backlog + README update	Haiku

For Java projects with DbC enabled, JML is used as the contract language and four dedicated skills are included (jml-design, jml-test-generation, jml-conformance-check, jml-completeness-check).

The Model column indicates which Claude model is recommended for each step, based on the reasoning depth required.

---

Skills reference

Skills are prompt templates that guide Claude through recurring tasks. Each skill is a markdown file with a frontmatter description, trigger conditions, a checklist, and an output format.

Skill	Purpose	When to use
static-analysis	Structured code review by severity	After generating or modifying code
design-review	Validate data structure, invariants, complexity	Before implementing a new class
test-coverage-review	Identify missing test cases	After writing tests
api-consistency-check	Check naming, null handling, symmetry	After adding public methods
architecture-drift-check	Verify code matches documented design	After refactoring or before release
update-backlog	Update task tracking	End of every session
update-readme	Update project documentation	When API or roadmap changes
new-class	Full scaffolding procedure	When creating a new class
refactor-class	Structural improvement checklist	When cleaning up a class
jml-design	Write JML formal contracts	Java + DbC: during stub step
jml-test-generation	Derive tests from JML specs	Java + DbC: during TDD step
jml-conformance-check	Verify code matches JML specs	Java + DbC: after implementation
jml-completeness-check	Verify JML specs are complete	Java + DbC: after implementation

---

Supported languages

Language	Standards file	Test framework	Static analysis
Java	Oracle guidelines, Javadoc, Optional, JML	JUnit 5 (3-level testing)	Checkstyle, SpotBugs, JaCoCo
Python	PEP 8, type hints, Google docstrings	pytest (3-level testing)	mypy, ruff, pytest-cov
TypeScript	Strict TS, JSDoc, ESLint	vitest (3-level testing)	ESLint, tsc, vitest coverage

Adding a new language: create a templates/standards/<language>/STANDARDS.md file following the structure of the existing ones, and add a case in the init scripts.

---

Three-level testing

All languages follow the same testing philosophy:

1. Interface / contract test — tests the interface in isolation using a mock implementation. No knowledge of any concrete class.
2. Black-box test — tests the concrete implementation through its public API. No knowledge of internals.
3. White-box test — tests implementation-specific risks (resize boundaries, collisions, lock ordering). Each test explains why it exists.

---

Usage with Claude

1. Point Claude to .dev/CONTEXT.md at the start of each session (e.g. via CLAUDE.md or by asking Claude to read it)
2. Follow the workflow steps in order
3. Claude will read the relevant skill files when it encounters the corresponding task
4. At the end of each session, Claude runs update-backlog and update-readme

Example CLAUDE.md integration

At the beginning of each session, read `.dev/CONTEXT.md` and follow all
instructions therein before generating or modifying any code.

---

Contributing

Contributions are welcome. To add a feature:

1. Fork the repository
2. Create a branch
3. Make your changes
4. Submit a pull request

To add support for a new language, create templates/standards/<language>/STANDARDS.md and add the corresponding case in init.sh and init.cmd.

---

License

MIT