This tutorial walks you through setting up kdd-tools, creating your first KDD specification, and validating it. By the end, you'll have a working KDD workflow with Claude Code.
Before starting, verify you have these installed:
| Prerequisite | Verify With | Minimum Version |
|---|---|---|
| Claude Code | claude --version |
Latest |
| Bun | bun --version |
1.0+ |
| kdd-specs | Check it's cloned locally | v2.0 |
projects/
├── kdd/ ← kdd-specs: methodology + templates
├── kdd-tools/ ← this repo
└── your-project/
├── specs/ ← your KDD specifications
└── .claude/settings.local.json
Choose one of these options — pick what fits your workflow.
cd your-project
claude --plugin-dir ../kdd-tools/platforms/claude-codeThis loads the plugin for the current session only. Ideal for developing or testing changes to the plugin.
ln -s "$(realpath kdd-tools/platforms/claude-code)" ~/.claude/plugins/kddCreates a persistent symlink so changes in the repo are immediately available. You only need to do this once.
cp -r kdd-tools/platforms/claude-code ~/.claude/plugins/kddFrom inside Claude Code, add the marketplace and install the plugin:
/plugin marketplace add knowledge-driven-dev/kdd-tools
/plugin install kdd@kdd-tools
The marketplace is backed by the GitHub repo — updates are fetched automatically.
Once inside Claude Code, type /kdd: — you should see autocomplete suggestions for all 10 commands:
/kdd:init /kdd:validate /kdd:generate-story
/kdd:feature /kdd:validate-deps /kdd:sync-story
/kdd:ui /kdd:list-entities
/kdd:fix-spec /kdd:analyze-entities
KDD v2.0 uses a layered folder structure. You can set it up automatically or manually.
/kdd:init --all --no-confirm
This creates all spec directories, copies reference templates, installs a pre-commit validation hook, and adds a validate:specs script to your package.json. Run /kdd:init without arguments for an interactive menu where you can pick individual components.
Create the full directory tree:
mkdir -p specs/{00-requirements,01-domain/{entities,events,rules},02-behavior/{commands,queries,use-cases,processes,policies},03-experience/{views,components,flows},04-verification/{criteria,examples},05-architecture/decisions}Your specs directory should now look like:
specs/
├── 00-requirements/
├── 01-domain/
│ ├── entities/
│ ├── events/
│ └── rules/
├── 02-behavior/
│ ├── commands/
│ ├── queries/
│ ├── use-cases/
│ ├── processes/
│ └── policies/
├── 03-experience/
│ ├── views/
│ ├── components/
│ └── flows/
├── 04-verification/
│ ├── criteria/
│ └── examples/
└── 05-architecture/
└── decisions/
Let's use Feature Discovery to create your first specifications. In Claude Code:
/kdd:feature Users should be able to create an account with email and password
Claude will:
- Read your existing domain (empty for now — that's fine)
- Ask clarifying questions one phase at a time:
- What problem does account creation solve?
- What entities are involved (User, Account)?
- What rules apply (password strength, email uniqueness)?
- How does the user interact with this?
- Walk through a happy-path example
- Show a structured summary of artifacts to create:
## Summary: User Account Creation
### Domain Impact (01-domain/)
| Type | Artifact | Action |
|--------|-------------|--------|
| Entity | User | Create |
| Event | EVT-User-Created | Create |
| Rule | BR-USER-001 | Create |
### Behavior (02-behavior/)
| Type | Artifact | Action |
|----------|--------------------------|--------|
| Command | CMD-001-CreateAccount | Create |
| Use Case | UC-001-CreateAccount | Create |
- Ask for confirmation, then generate the files
After approval, you'll have spec files in the appropriate directories with proper frontmatter, wiki-links, and section structure.
Now check that the generated specs are correct:
/kdd:validate
The validator runs three levels of checks on every .md file in specs/:
specs/01-domain/entities/User.md
✓ All checks passed
specs/02-behavior/use-cases/UC-001-CreateAccount.md
⚠ semantics/unlinked: "password" (line 24) — consider documenting as entity
specs/01-domain/rules/BR-USER-001.md
✗ frontmatter/missing: Required field "id" is missing
──────────────────────────────────────────────────
5 files, 1 error, 1 warning
✗Errors must be fixed before the specs are valid⚠Warnings should be reviewed but may be intentionalℹInfo suggestions appear with--verboseflag
For the error above, run the auto-fixer on the specific file:
/kdd:fix-spec specs/01-domain/rules/BR-USER-001.md
Output:
Corrections applied (2):
✓ Added frontmatter field "id: BR-001"
✓ Line 12: "User" → "[[User]]"
Require manual intervention (0):
(none)
Run validation again to confirm:
/kdd:validate
──────────────────────────────────────────────────
5 files, 0 errors, 1 warning
Zero errors — your specs are valid.
While you were running commands, kdd-tools was also working automatically through skills, rules, and hooks:
| Mechanism | What Happened |
|---|---|
| kdd-methodology skill | Loaded KDD v2.0 reference when you started /kdd:feature |
| spec-writing skill | Provided frontmatter schemas when generating specs |
| kdd-writing rule | Applied writing conventions (capitalization, wiki-links) to every spec |
| Type-specific rules | Applied artifact-specific structure (e.g., kdd-domain-entities.md for entity files) |
| PreToolUse:Write hook | Checked formatting before each spec was written |
| PostToolUse:Write hook | Verified wiki-links and frontmatter after each write |
You didn't need to know about these — they just ensured everything was correct. See Skills, Rules, and Hooks for the full reference.
If you already set up KDD in your project and pushed it to git, new team members only need to do the following after cloning:
claude --version # verify it's installed# Clone kdd-tools (once, alongside the project)
git clone https://github.com/knowledge-driven-dev/kdd-tools.git
# Persistent install via symlink
ln -s "$(realpath kdd-tools/platforms/claude-code)" ~/.claude/plugins/kddOr via Marketplace inside Claude Code:
/plugin marketplace add knowledge-driven-dev/kdd-tools
/plugin install kdd@kdd-tools
The .git/hooks/ directory is local and not tracked by git. After cloning, run inside Claude Code:
/kdd:init --hook --no-confirm
specs/— full directory structure and existing specsspecs/.templates/— reference templatespackage.json— withvalidate:specsscript
- The KDD plugin for Claude Code (step 2)
- The pre-commit validation hook (step 3)
Add something like this to your project's README to help new team members:
## KDD Setup
This project uses [KDD](https://github.com/knowledge-driven-dev/kdd-tools) for specification-driven development.
### First-time setup
1. Install the KDD plugin:
ln -s "$(realpath ../kdd-tools/platforms/claude-code)" ~/.claude/plugins/kdd
2. Install the pre-commit hook:
Open Claude Code and run `/kdd:init --hook --no-confirm`Now that you have a working KDD setup, explore these resources:
| Guide | What You'll Learn |
|---|---|
| Command Reference | All 10 /kdd:* commands with syntax, arguments, and examples |
| Skills, Rules, and Hooks | What activates automatically and when |
| Validator Guide | Deep dive into the three validation levels |
| Workflows | Common patterns: new feature, add UI, validate before PR, iterate |
| Storybook Workflow | Turn UI specs into Storybook wireframes |
| Validation Tooling | AI analysis commands and CI/CD integration |
| Graph RAG | Node types and edges for semantic indexing |
- Design a UI component:
/kdd:ui A card showing user profile with avatar - Check layer dependencies:
/kdd:validate-deps - See all entities:
/kdd:list-entities - Generate a Storybook wireframe:
/kdd:generate-story specs/03-experience/components/UI-UserCard.md - Ask Claude to review quality: "Review the User entity spec for completeness"
- Find what's missing: "What artifacts are missing for the account creation feature?"