Master Your AI Coding Agent

Write CLAUDE.md, SKILL.md, and SPEC docs to control Claude Code.

Introduction

30 Second Summary

Imagine hiring a brilliant engineer who has never seen your codebase. Without a briefing, they waste hours asking basic questions. AI coding agents work the same way. The quality of their output depends entirely on the clarity of your input.

In this project, you will create the essential documents that make Claude Code immediately effective on any project. You will write a project briefing, a reusable skill workflow, and a structured spec document that turns your intent into working code.

What You'll Build

A complete Claude Code workspace template containing all the foundational documents that communicate your intent to an AI coding agent.

By the end of this project, you'll have:

A production-ready CLAUDE.md that makes Claude Code immediately effective on your project.
A custom SKILL.md that extends Claude Code with a reusable, on-demand code review workflow.
A SPEC document with clear boundaries and verifiable deliverables that AI can execute without ambiguity.
A reference guide connecting IDD, SDD, and the harness concept into a complete AI-assisted development workflow.
Secret Mission: Build a full IDD hierarchy for a real mini-feature and execute it with Claude Code.

Are there any prerequisites?

You need VS Code with the Claude Code extension already installed and signed in. You also need Python installed on your machine. No prior experience with AI coding agents or documentation frameworks is required.

Set Up Your Workspace

The tools you use are only as effective as the context you give them. Claude Code can read files, run commands, and write code. But without clear documentation about your project, it starts every session guessing.

In this step, you'll create a dedicated workspace folder and set up the directory structure that Claude Code uses to find your project documents. You'll also confirm that Claude Code is responding inside your workspace.

In this step, get ready to:

Create a project folder on your Desktop.
Set up the folder structure for Claude Code documents.
Verify Claude Code is responding in your workspace.

Create your project folder and open it in VS Code

Every project needs a home. You'll create a folder on your Desktop so it's easy to find, then open it in VS Code so all your work happens in one place.

In VS Code, open the integrated terminal by clicking Terminal in the top menu bar, then selecting New Terminal.
Move to your Desktop by running this command:

cd ~/Desktop

Create your project folder by running this command:

mkdir ai-workspace

Confirm the folder exists by running:

ls

You should see ai-workspace listed in the output.

Now open that folder in VS Code. Click File in the top menu bar.
Click Open Folder.
Navigate to your Desktop, select the ai-workspace folder, and click Open.

Why open the folder this way?

When you open a folder in VS Code, it becomes your workspace root. Claude Code uses this root to locate your project documents and understand what it's working with.

Open the Claude Code panel by clicking the Spark icon in the Activity Bar on the left side of VS Code.

Can't find the Spark icon?

Press Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows) to open the Command Palette, then type Claude Code and select the option that appears.

Don't see the Spark icon or the Claude Code option?

Make sure the Claude Code extension is installed and you are signed in. Check the Extensions panel (the square icon in the Activity Bar) and search for Claude Code to confirm it's enabled.

help me troubleshoot why Claude Code isn't appearing in my VS Code Activity Bar

Create the project folder structure

Claude Code looks for documents in specific locations. The .claude/ directory holds skills and rules that Claude loads automatically. The docs/ folder is where you'll store reference materials like specs and methodology guides.

If VS Code opened a new window, open a fresh terminal by clicking Terminal in the top menu bar, then selecting New Terminal. This terminal opens inside your ai-workspace folder automatically.
Create the folder structure by running these commands:

macOS

mkdir -p .claude/skills .claude/rules docs

Windows

mkdir .claude/skills
mkdir .claude/rules
mkdir docs

What do these folders do?

.claude/skills/ stores on-demand workflows that Claude runs when you invoke them. .claude/rules/ holds topic-specific instructions that Claude loads based on file paths.

docs/ is your space for specs, methodology guides, and any reference material you want Claude to access.

Confirm the folders were created by running:

ls -la

You should see .claude and docs listed in the output.

Verify the nested folders by running:

ls .claude

You should see rules and skills listed.

Don't see the .claude folder?

Folders starting with a dot are hidden by default. Use ls -la (not just ls) to show hidden files. On Windows PowerShell, use ls -Force instead.

help me see hidden folders in my terminal

Verify Claude Code is working

Before writing any documents, confirm that Claude Code can see your workspace. A quick test message proves the connection is live and Claude knows where it is.

Click into the Claude Code panel's input field at the bottom.
Type the following message and press Enter:

What folder am I in?

What should I see?

Claude Code should respond with the full path to your ai-workspace folder. Something like /Users/yourname/Desktop/ai-workspace on macOS or C:\Users\yourname\Desktop\ai-workspace on Windows.

This confirms Claude Code is connected and aware of your project root.

Claude Code might ask for permission

The first time Claude Code runs a command or reads a file, it may ask you to approve the action. Click Allow to let it proceed. This is normal security behavior.

Claude Code not responding?

Make sure you are signed in to your Anthropic Claude account. Click the Spark icon in the Activity Bar and check if there's a sign-in prompt at the top of the panel.

Also confirm your internet connection is active. Claude Code requires a network connection to process messages.

help me fix Claude Code not responding in VS Code

✔️ Awesome, I've got everything!

Great. Double check you have the .claude/skills/, .claude/rules/, and docs/ folders in your ai-workspace directory, and that Claude Code responded to your test message.

ⓧ I'd like to double check the full structure

Your ai-workspace folder should contain this structure:

.claude/
  skills/
  rules/
docs/

All three folders should be empty for now. You'll add files to them in the next steps.

Your workspace is ready. Next up, you'll write your first CLAUDE.md to give Claude Code a complete briefing on your project.

Write Your CLAUDE.md

Your workspace is ready with the right folder structure. Now it's time to write the single most important document in your project: the briefing that tells Claude Code what it's working on.

Without a CLAUDE.md, Claude Code starts every conversation with zero knowledge of your codebase. It doesn't know your commands, your conventions, or your constraints. Writing a good briefing fixes that.

In this step, get ready to:

Understand what CLAUDE.md is and why it matters.
Write a complete CLAUDE.md with five key sections.
Test your CLAUDE.md by verifying Claude can describe your project.

Understand what CLAUDE.md does

CLAUDE.md is the briefing Claude Code reads at the start of every session. It gets loaded into Claude's context window automatically, so Claude knows your project before you type a single prompt.

Think of it as answering the questions a senior engineer would ask in their first 30 minutes on a new codebase: What is this project? What are the commands? What are the conventions? What should I never do?

Why does CLAUDE.md need to be concise?

The official guidance is to keep CLAUDE.md under 200 lines. Longer files consume more of Claude's context window and reduce how well it follows your instructions.

Write instructions that are concrete enough to verify. For example, "Use 2-space indentation" is better than "Format code properly."

Write your CLAUDE.md

You'll build your CLAUDE.md using a sample scenario: a Python analytics dashboard built with pandas and Streamlit for a retail team. This gives you a realistic template you can adapt for any future project.

Create a new file called CLAUDE.md in your project root (the top level of your project folder, alongside the .claude/ and docs/ folders).
Paste the following into CLAUDE.md. This covers the project identity and the commands Claude needs to know:

# Project: Data Analytics Dashboard

A Python-based analytics dashboard that visualizes sales data for a retail team. Built with pandas for data processing and Streamlit for the interactive UI. Used by 3 business analysts who need daily KPI tracking.

## Commands

- Run app: `streamlit run app.py`
- Run tests: `pytest tests/`
- Lint: `ruff check .`
- Format: `ruff format .`

What does this section do?

The heading and first paragraph tell Claude what this project is, who uses it, and what tech stack it runs on. Claude uses this to make relevant suggestions from the very first prompt.

The Commands section lists every action Claude might need to run. Without it, Claude would guess at command names or ask you every time.

Now add the remaining three sections below your Commands section. These tell Claude how to behave in this codebase:

## Conventions

- File naming: snake_case for all Python files
- Imports: standard library first, then third-party, then local (separated by blank lines)
- Error handling: use explicit try/except with specific exceptions, never bare except
- Data functions: all data processing lives in `src/data/`, never inline in UI components
- Charts: all visualization functions live in `src/charts/`, return Plotly figure objects

## Architecture

- `app.py` - Streamlit entry point, layout only
- `src/data/` - data loading, cleaning, transformations
- `src/charts/` - visualization functions
- `src/utils/` - shared helpers
- `tests/` - mirrors src/ structure
- `data/` - raw CSV files (gitignored)

## Rules

- Never modify files in `data/` - they are read-only source files
- Never commit .env or any file containing credentials
- Never use `st.cache_data` without a TTL parameter
- Always include a docstring on public functions
- The app must remain functional after every change - no half-finished features

What do these three sections do?

Conventions sets the style rules Claude must follow when writing code. These prevent Claude from mixing patterns (like using camelCase in one file and snake_case in another).

Architecture is a map of where things live. Without it, Claude might create new files in the wrong place or miss existing helpers.

Rules are hard constraints that Claude must never violate. These are the "do not" items that prevent costly mistakes.

Save CLAUDE.md.
Confirm your file has five sections: a project heading with a description paragraph, Commands, Conventions, Architecture, and Rules.

File not saving in the right place?

Make sure CLAUDE.md is at the top level of your project folder, not inside .claude/ or docs/. It should sit alongside those folders, not inside them.

Also check the filename is uppercase: CLAUDE.md not claude.md. Claude Code looks for this exact filename.

Having trouble? Help me figure out where my CLAUDE.md should go in my project folder.

✔️ Awesome, I've got everything!

Great. Make sure you've saved CLAUDE.md before moving on to testing.

ⓧ I'd like to double check the full code

Here's the complete CLAUDE.md file. Make sure yours matches this exactly:

# Project: Data Analytics Dashboard

A Python-based analytics dashboard that visualizes sales data for a retail team. Built with pandas for data processing and Streamlit for the interactive UI. Used by 3 business analysts who need daily KPI tracking.

## Commands

- Run app: `streamlit run app.py`
- Run tests: `pytest tests/`
- Lint: `ruff check .`
- Format: `ruff format .`

## Conventions

- File naming: snake_case for all Python files
- Imports: standard library first, then third-party, then local (separated by blank lines)
- Error handling: use explicit try/except with specific exceptions, never bare except
- Data functions: all data processing lives in `src/data/`, never inline in UI components
- Charts: all visualization functions live in `src/charts/`, return Plotly figure objects

## Architecture

- `app.py` - Streamlit entry point, layout only
- `src/data/` - data loading, cleaning, transformations
- `src/charts/` - visualization functions
- `src/utils/` - shared helpers
- `tests/` - mirrors src/ structure
- `data/` - raw CSV files (gitignored)

## Rules

- Never modify files in `data/` - they are read-only source files
- Never commit .env or any file containing credentials
- Never use `st.cache_data` without a TTL parameter
- Always include a docstring on public functions
- The app must remain functional after every change - no half-finished features

Test your CLAUDE.md in a fresh conversation

The real test of a good CLAUDE.md is whether Claude can accurately describe your project after reading it. If Claude gets something wrong, that section needs to be clearer.

Open the Command Palette by pressing Ctrl+Shift+P (Windows) or Cmd+Shift+P (macOS).
Type Claude Code: Open in New Tab and press Enter. This starts a fresh conversation where Claude re-reads your CLAUDE.md from scratch.
Type this prompt into the Claude Code panel:

Describe this project. What is it, what tech does it use, and what are the key rules I should know about?

Press Enter to send the message.
Read Claude's response. It should mention the Python dashboard, pandas, Streamlit, the retail team, and at least some of your Rules (like never modifying the data/ folder).

What if Claude gets something wrong?

If Claude misses a section or describes something inaccurately, that's a signal your CLAUDE.md needs to be clearer in that area. Rewrite the unclear section, save the file, then start another fresh conversation and test again.

This iterative testing is the key skill. A CLAUDE.md that reads well to humans but confuses Claude is not done yet.

Claude didn't mention your project details?

Make sure you started a fresh conversation using the Command Palette method above. If you typed into an existing conversation, Claude may not have re-read your CLAUDE.md.

Also verify your file is named exactly CLAUDE.md and is in the project root. Claude Code only auto-loads it from the top level of your workspace.

Help me troubleshoot why Claude Code isn't reading my CLAUDE.md file.

Your project now has a briefing document that makes Claude Code immediately effective. Next up, you'll create a SKILL.md that teaches Claude a reusable workflow it can run on demand.

Write Your First SKILL.md

Your CLAUDE.md gives Claude Code the knowledge it needs every session. But what about tasks you run repeatedly?

If you keep pasting the same multi-step instructions into chat ("review this code for bugs, check the naming, output a summary..."), that repetition belongs in a SKILL.md. Skills are on-demand procedures Claude runs when you trigger them. In this step, you will create a reusable code-review skill and test it on a real file.

In this step, get ready to:

Understand when to use a SKILL.md vs CLAUDE.md.
Create a code-review skill with YAML frontmatter and a structured workflow.
Test the skill by invoking it on a file with intentional issues.

Understand when to use a SKILL.md vs CLAUDE.md

Both files give Claude Code instructions, but they load at different times and serve different purposes.

CLAUDE.md loads every session. It contains facts Claude should always know: project context, conventions, architecture.
SKILL.md loads on demand. It contains procedures Claude runs when triggered by you.

How do I know something belongs in a skill?

Ask yourself: do I keep pasting the same multi-step instructions into chat? If yes, that's a skill. The instructions become a reusable workflow that Claude executes whenever you invoke it.

Think of CLAUDE.md as a reference sheet pinned to the wall. SKILL.md is a checklist you hand to someone when it's time to perform a specific procedure.

Create your code-review skill

Skills live in .claude/skills/ and are organized by name. Each skill gets its own folder containing a SKILL.md file.

Create the code-review folder inside .claude/skills/ by running this command in your terminal:

mkdir .claude/skills/code-review

Confirm the folder exists by running:

ls .claude/skills/

You should see code-review listed in the output.

Create a new file called SKILL.md inside the code-review folder. In VS Code's Explorer sidebar, right-click the code-review folder and select New File.
Name the file SKILL.md.

Now you will write the skill content. A SKILL.md has two parts: YAML frontmatter (metadata between --- markers) and a markdown body with the actual workflow instructions.

Paste the following into your SKILL.md file:

---
description: Reviews code for style, bugs, and improvements. Use when the user asks for a code review, wants feedback on their code, or says "review this."
disable-model-invocation: true
---

## Code Review Workflow

Review the code the user points you to. Follow this structure:

### 1. Style Check
- Verify naming conventions match CLAUDE.md
- Check import ordering
- Flag missing docstrings on public functions
- Check line length and formatting

### 2. Bug Scan
- Look for unhandled exceptions
- Check for potential None/null issues
- Identify race conditions or state mutations
- Flag hardcoded values that should be config

### 3. Improvements
- Suggest clearer variable names where needed
- Identify repeated logic that could be extracted
- Note any performance concerns with data operations

### 4. Output Format

Provide your review as:

**Summary**: One sentence overall assessment.

**Issues** (must fix):
- [file:line] description

**Suggestions** (nice to have):
- [file:line] description

**Verdict**: PASS / NEEDS CHANGES

What does this skill do?

The YAML frontmatter defines two things. description tells Claude when this skill is relevant. disable-model-invocation: true means Claude will only run this skill when you manually invoke it, not automatically.

The markdown body is the actual procedure. It gives Claude a four-step structure: check style, scan for bugs, suggest improvements, then format the output consistently. The structured output format means you get the same review shape every time.

Save SKILL.md.

File not showing in the right place?

Make sure the file path is exactly .claude/skills/code-review/SKILL.md. If you accidentally created it in the wrong folder, drag it to the correct location in the Explorer sidebar.

help me verify my SKILL.md is in the correct location

✔️ Awesome, I've got everything!

Great. Double check you have saved your file before moving on.

ⓧ I'd like to double check the full code

Your .claude/skills/code-review/SKILL.md should look exactly like this:

---
description: Reviews code for style, bugs, and improvements. Use when the user asks for a code review, wants feedback on their code, or says "review this."
disable-model-invocation: true
---

## Code Review Workflow

Review the code the user points you to. Follow this structure:

### 1. Style Check
- Verify naming conventions match CLAUDE.md
- Check import ordering
- Flag missing docstrings on public functions
- Check line length and formatting

### 2. Bug Scan
- Look for unhandled exceptions
- Check for potential None/null issues
- Identify race conditions or state mutations
- Flag hardcoded values that should be config

### 3. Improvements
- Suggest clearer variable names where needed
- Identify repeated logic that could be extracted
- Note any performance concerns with data operations

### 4. Output Format

Provide your review as:

**Summary**: One sentence overall assessment.

**Issues** (must fix):
- [file:line] description

**Suggestions** (nice to have):
- [file:line] description

**Verdict**: PASS / NEEDS CHANGES

Test your skill on a file with intentional issues

A skill is only useful if it produces the output you expect. You will create a small Python file with deliberate problems, then invoke the skill to see if it catches them.

Create a test file called test_sample.py in your project root by running:

touch test_sample.py

Open test_sample.py and paste the following code with intentional issues:

import os
import pandas as pd
import sys

def loadData(filepath):
    data = pd.read_csv(filepath)
    return data

def process(x):
    result = x * 2
    return result

What issues are hiding in this file?

This file breaks several conventions from your CLAUDE.md. The imports are out of order (os and sys are standard library but aren't grouped together). loadData uses camelCase instead of snake_case. Neither function has a docstring.

These are exactly the kinds of issues your code-review skill is designed to catch.

Save test_sample.py.
Switch to the Claude Code panel in VS Code.
Type /code-review in the Claude Code input to invoke your skill.
When Claude asks which file to review, point it to test_sample.py.

Claude should respond with a structured review following the exact format from your skill: a Summary, Issues, Suggestions, and a Verdict.

What should I see?

Claude's response should flag the import ordering issue, the camelCase naming violation, and the missing docstrings. The output should follow the structured format you defined: Summary, Issues (must fix), Suggestions (nice to have), and a Verdict of NEEDS CHANGES.

The exact wording will vary, but the structure should match your skill's Output Format section.

Skill not found or output looks unstructured?

If typing /code-review does not trigger the skill, check that your file is saved at exactly .claude/skills/code-review/SKILL.md. The folder name must match what you type after the slash.

If the output does not follow your structured format, check that the ## Code Review Workflow heading and numbered sections are properly formatted in your skill file.

help me troubleshoot why my Claude Code skill is not working

You now have a reusable skill that produces consistent, structured code reviews on demand. Next up, you will write a SPEC document that gives Claude clear build instructions for a feature.

Write a SPEC Document

Your CLAUDE.md gives Claude Code project-level context, and your SKILL.md gives it an on-demand workflow. The missing piece is a way to tell Claude Code exactly what to build for a specific feature.

Without clear instructions, AI agents make assumptions. They add features you did not ask for, change files you needed left alone, and miss edge cases you would have caught in a review. A SPEC document eliminates that ambiguity by translating your expectations into structured, verifiable build instructions.

In this step, get ready to:

Learn what a SPEC is and why it matters for AI-assisted development.
Write a five-section SPEC document for a sample dashboard feature.
Run an adversarial gap-check to find and fix ambiguities before execution.

Understand what a SPEC is

A Spec is the translation layer between what you want and what an AI coding agent builds. It converts human expectations into structured instructions that Claude Code can execute with minimal ambiguity.

A good Spec answers four questions:

What are we building?
What are the boundaries (what AI must NOT do)?
What are the deliverables (exact files and outputs expected)?
How will we verify success?

Why boundaries matter more than requirements

AI agents are eager to help. Without explicit "do not" constraints, Claude Code may refactor adjacent code, add dependencies you did not approve, or change a working UI layout while implementing a new feature.

Boundaries are the guardrails that keep the agent focused on exactly what you asked for.

How is a SPEC different from CLAUDE.md?

Your CLAUDE.md is a permanent briefing loaded every session. A SPEC is a one-time build document for a specific feature. Think of CLAUDE.md as "who you are" and the SPEC as "what to build right now."

Write your SPEC document

You will write a SPEC for a sample feature: adding a date filter to the analytics dashboard. The five sections map directly to the four questions above, plus a Context section that orients the agent.

Create a new file called spec-date-filter.md inside your docs/ folder.
Paste the following content into the file:

# SPEC: Add Date Filter to Dashboard

## Context

The dashboard currently shows all-time data with no way to filter by date range. Business analysts have requested the ability to narrow the view to specific time periods.

## Requirements

1. Add a date range picker to the sidebar that filters all charts and KPIs
2. Default range: last 30 days
3. Minimum selectable date: earliest date in the dataset
4. Maximum selectable date: today
5. When the date filter changes, all charts and the KPI summary must update immediately

## Boundaries

- DO NOT modify the raw data files or data loading logic
- DO NOT change the existing chart color scheme or layout
- DO NOT add any new Python dependencies
- OUT OF SCOPE: saved filter presets, export functionality, date comparison mode

## Deliverables

- Modified `app.py` with date picker in sidebar
- New function in `src/data/filters.py` that accepts a DataFrame and date range, returns filtered DataFrame
- Updated tests in `tests/test_filters.py` covering: valid range, empty result, boundary dates
- No changes to any other existing files

## Verification

1. App starts without errors after changes
2. Date picker appears in sidebar with correct default (last 30 days)
3. Changing dates updates all visible charts
4. Selecting a range with no data shows a clear "No data for selected range" message
5. All tests pass: `pytest tests/test_filters.py`

What does each section do?

Context tells the agent what exists today and why this feature is needed. Without it, the agent guesses at the current state.
Requirements are specific, numbered, and verifiable. Each one describes a concrete behavior.
Boundaries use "DO NOT" and "OUT OF SCOPE" to prevent scope creep. These are the most important lines in the spec.
Deliverables name exact files so the agent knows what to create and what to leave alone.
Verification gives you a checklist to confirm the feature works. Every criterion is testable.

Save docs/spec-date-filter.md.
In the Explorer sidebar, confirm spec-date-filter.md appears inside the docs/ folder.

File not showing up in the Explorer?

Make sure you created the file inside docs/ and not in the project root. The path should be docs/spec-date-filter.md.
Check that you saved the file (look for a dot on the tab indicating unsaved changes).

Still stuck? Why isn't my spec file appearing in the docs folder?

Run a gap-check on your SPEC

The real skill in writing specs is not the first draft. It is finding the ambiguities before the agent does. You will now use Claude Code as an adversarial reviewer to stress-test your spec.

Switch to the Claude Code panel.
Start a fresh conversation by pressing Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows), typing Claude Code, and selecting Open in New Tab.
Type the following prompt and press Enter:

Read docs/spec-date-filter.md and list every ambiguity, missing edge case, or assumption that could cause you to build the wrong thing.

What should I expect back?

Claude will return a list of gaps it found. Common findings include questions like: What date format does the dataset use? What happens if the dataset has no date column? Should the picker use calendar dropdowns or text inputs?

Each gap represents a decision you would have had to make mid-build. By surfacing them now, you prevent the agent from guessing wrong during execution.

Review the gaps Claude identified.
For each gap that matters, update your docs/spec-date-filter.md with a clarification. Add specifics to the Requirements or Boundaries sections as needed.
Save your updated spec.

You do not need to fix every gap

Some gaps Claude surfaces are theoretical edge cases that do not apply to your project. Focus on the ones that could lead the agent to make a wrong architectural decision or touch files it should not.

Why this adversarial review matters

This gap-check loop is the key skill that separates good specs from bad ones. A spec without a gap-check is a first draft. A spec that has survived adversarial review is a reliable build document.

Get into the habit of running this review on every spec before you ask Claude Code to execute it.

✔️ Awesome, I've got everything!

Great. Double check you have saved docs/spec-date-filter.md with your gap-check fixes applied.

ⓧ I'd like to double check the full code

Here is the base spec before your gap-check additions. Your file should contain at least this content (plus any clarifications you added):

# SPEC: Add Date Filter to Dashboard

## Context

The dashboard currently shows all-time data with no way to filter by date range. Business analysts have requested the ability to narrow the view to specific time periods.

## Requirements

1. Add a date range picker to the sidebar that filters all charts and KPIs
2. Default range: last 30 days
3. Minimum selectable date: earliest date in the dataset
4. Maximum selectable date: today
5. When the date filter changes, all charts and the KPI summary must update immediately

## Boundaries

- DO NOT modify the raw data files or data loading logic
- DO NOT change the existing chart color scheme or layout
- DO NOT add any new Python dependencies
- OUT OF SCOPE: saved filter presets, export functionality, date comparison mode

## Deliverables

- Modified `app.py` with date picker in sidebar
- New function in `src/data/filters.py` that accepts a DataFrame and date range, returns filtered DataFrame
- Updated tests in `tests/test_filters.py` covering: valid range, empty result, boundary dates
- No changes to any other existing files

## Verification

1. App starts without errors after changes
2. Date picker appears in sidebar with correct default (last 30 days)
3. Changing dates updates all visible charts
4. Selecting a range with no data shows a clear "No data for selected range" message
5. All tests pass: `pytest tests/test_filters.py`

You now have a complete, reviewed SPEC document. In the next step, you will connect all three documents together and see how IDD, SDD, and the Claude Code harness form a complete AI-assisted development workflow.

Connect the Dots — IDD, SDD, and the Harness

You now have a CLAUDE.md that briefs Claude, a SKILL.md that gives Claude a reusable procedure, and a SPEC that tells Claude exactly what to build. These are powerful documents on their own.

But how do they fit together into a coherent workflow? In this step, you will map three concepts that connect your documents into a complete development methodology: Intent-Driven Development (IDD), Spec-Driven Development (SDD), and the agentic harness.

In this step, get ready to:

Understand how IDD, SDD, and the Harness relate to each other.
Create a reference document mapping the full development flow.
Wire your documents together and verify the full loop works.

Understand the three concepts

Before you write anything, you need a mental model of how these three ideas relate. Each one answers a different question in the development lifecycle.

What is the Harness?

The Harness is Claude Code itself. It provides tools (file read/write, terminal, web search), context management (CLAUDE.md, memory, skills), and the execution environment that turns Claude into a capable coding agent.

Without the harness, Claude can only respond with text. With it, Claude can act.

What is IDD (Intent-Driven Development)?

IDD is the upstream methodology that answers "what to spec and why." It decomposes human intent into four levels: Product > Intention > Expectation > Spec.

Think of IDD as the planning phase. It ensures you are building the right thing before you hand off instructions to an AI agent.

What is SDD (Spec-Driven Development)?

SDD is the downstream pipeline that answers "how to execute the spec." It follows the path: Spec > Design > Tasks > Implementation > Review > Ship.

The Spec is the handoff point between IDD and SDD. IDD decides what to build, the Spec captures that decision, and SDD executes it through the Harness.

How do they connect?

Together, the flow is: IDD decides what to build, the Spec is the handoff document, SDD executes it, and the Harness (Claude Code) is what runs it all.

Your CLAUDE.md, SKILL.md, and SPEC documents are the practical artifacts that plug into this flow.

Create your methodology reference document

Now that you understand the concepts, you will create a reference document that maps the full flow. This gives you (and Claude) a single place to look up which document serves which purpose.

Create a new file called docs/methodology.md by pasting the following content:

# AI-Assisted Development Methodology

## The Flow

Human Intent > IDD Hierarchy > SPEC > SDD Pipeline > Claude Code Harness > Working Code

## Document Purpose Map

| Document | Purpose | When to Create | When to Update |
|----------|---------|----------------|----------------|
| CLAUDE.md | Project briefing for every session | Project start | When conventions change |
| SKILL.md | Reusable on-demand workflow | When you repeat instructions | When the workflow improves |
| SPEC | AI-ready build instructions | Before each feature | When requirements change |
| IDD artifacts | Why and what to build | Planning phase | When direction shifts |

## IDD Hierarchy (Upstream - decides WHAT)

- Product: Why does this exist? Who does it serve?
- Intention: What should this feature accomplish?
- Expectation: How will we know it is right? (verifiable criteria)
- Spec: How does AI build it? (boundaries + deliverables)

## SDD Pipeline (Downstream - executes HOW)

Spec > Design > Tasks > Implementation > Review > Ship

## The Harness (Claude Code)

Claude Code is the agentic harness: it provides tools (file read/write, terminal, web search), context management (CLAUDE.md, memory, skills), and the execution environment that turns Claude into a capable coding agent. Without the harness, Claude can only respond with text. With it, Claude can act.

## Key Principle

Speed without clarity produces rapid failure. Define intent clearly (IDD), translate it into unambiguous instructions (SPEC), then let the agent execute (SDD via the Harness). The quality of your output is bounded by the quality of your input.

What does this document do?

The Flow section shows the entire pipeline from human thought to working code in one line.
The Document Purpose Map is a quick-reference table so you know when to create or update each document type.
The IDD and SDD sections describe the upstream (what to build) and downstream (how to execute) halves of the workflow.
The Harness section explains what Claude Code actually provides as an execution environment.
The Key Principle is a reminder that clarity of input determines quality of output.

Save docs/methodology.md.
Confirm the file exists in the docs/ folder in your VS Code Explorer sidebar alongside spec-date-filter.md.

Don't see the file in your Explorer?

Make sure you saved the file in the docs/ folder, not in the project root. The file path should be docs/methodology.md relative to your project folder.

If the docs/ folder is collapsed in the sidebar, click the arrow next to it to expand.

help me find where my methodology.md file was saved

✔️ Awesome, I've got everything!

Great. Make sure you have saved docs/methodology.md before moving on.

ⓧ I'd like to double check the full code

Here is the complete docs/methodology.md file for comparison:

# AI-Assisted Development Methodology

## The Flow

Human Intent > IDD Hierarchy > SPEC > SDD Pipeline > Claude Code Harness > Working Code

## Document Purpose Map

| Document | Purpose | When to Create | When to Update |
|----------|---------|----------------|----------------|
| CLAUDE.md | Project briefing for every session | Project start | When conventions change |
| SKILL.md | Reusable on-demand workflow | When you repeat instructions | When the workflow improves |
| SPEC | AI-ready build instructions | Before each feature | When requirements change |
| IDD artifacts | Why and what to build | Planning phase | When direction shifts |

## IDD Hierarchy (Upstream - decides WHAT)

- Product: Why does this exist? Who does it serve?
- Intention: What should this feature accomplish?
- Expectation: How will we know it is right? (verifiable criteria)
- Spec: How does AI build it? (boundaries + deliverables)

## SDD Pipeline (Downstream - executes HOW)

Spec > Design > Tasks > Implementation > Review > Ship

## The Harness (Claude Code)

Claude Code is the agentic harness: it provides tools (file read/write, terminal, web search), context management (CLAUDE.md, memory, skills), and the execution environment that turns Claude into a capable coding agent. Without the harness, Claude can only respond with text. With it, Claude can act.

## Key Principle

Speed without clarity produces rapid failure. Define intent clearly (IDD), translate it into unambiguous instructions (SPEC), then let the agent execute (SDD via the Harness). The quality of your output is bounded by the quality of your input.

Wire it all together and verify the loop

Your documents exist, but they do not reference each other yet. In this substep, you will ask Claude Code to connect them and then verify the full workflow loop.

Switch back to the Claude Code panel.
Start a fresh conversation by pressing Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows), then selecting Claude Code: Open in New Tab.
Ask Claude to update your CLAUDE.md to reference the methodology document by typing this message:

Update my CLAUDE.md to add a brief reference to docs/methodology.md under a new "## References" section at the bottom. Just a one-liner pointing to it as the full development methodology guide.

Review the change Claude proposes and accept it.
Next, ask Claude to enhance your code-review skill with a gap-check step by typing this message:

Update .claude/skills/code-review/SKILL.md to add a "### 5. Spec Gap Check" section after the Output Format section. This new step should: validate that any referenced spec has clear boundaries, verify deliverables are specific and testable, and flag any ambiguity that could cause Claude to build the wrong thing.

Review the change Claude proposes and accept it.

Why ask Claude to make these edits?

This is Intent-Driven Development in action. You described what you wanted (your intent), and the Harness (Claude Code) executed it.

You could have edited the files manually. But using Claude to make the changes demonstrates the full loop you just documented: intent flows through a clear instruction, Claude executes, and you verify.

Now verify the full loop works by asking Claude to explain your project workflow.

Type the following message in Claude Code:

Read all my project docs (CLAUDE.md, the skill, the spec, and docs/methodology.md) and explain my full development workflow from intent to working code. How do the documents connect?

Read Claude's response. It should describe the flow from human intent through IDD, into a SPEC, executed via SDD, powered by the Harness.
Verify that Claude correctly references each document's role: CLAUDE.md as the project briefing, SKILL.md as the reusable procedure, and the SPEC as the build instructions.

Claude's explanation seems incomplete?

If Claude misses a document or gets the relationship wrong, that tells you the documents need clearer cross-references. Try rephrasing your prompt to mention specific files by path.

If Claude cannot find a file, check that all documents are saved and in the correct locations (CLAUDE.md in the project root, skills in .claude/skills/, docs in docs/).

Claude isn't explaining my workflow correctly, help me troubleshoot

Secret mission

Build a Full IDD Hierarchy and Execute It

You've written individual documents. Now put the entire Intent-Driven Development pipeline to the test. Build a complete IDD hierarchy for a real feature, hand it to Claude Code, and see if your intent is clear enough for autonomous execution.

Clean Up Your Resources

This project runs entirely locally with no cloud resources, so there are no ongoing costs. Decide whether to keep your files for future reference or delete them.

Resources you used:

Project folder on your Desktop (contains CLAUDE.md, .claude/ directory, and docs/ directory).

Keep everything running

No action needed. Choose this if you plan to reuse your workspace template as a starting point for future projects.

Your project folder stays on your Desktop with all documents intact.
You can copy the folder to new projects whenever you need a fresh CLAUDE.md, skill, or spec template.
VS Code and the Claude Code extension remain installed as they were before this project.

Pause - I'll come back to this later

Since everything is local files, there is nothing to pause. Your project folder will sit on your Desktop until you return.

Close the project in VS Code by clicking File, then Close Folder.
When you want to return, reopen the folder in VS Code and your documents will be exactly as you left them.

Delete - I don't want to use this again

Remove the entire project folder from your Desktop. This deletes all documents you created during the project.

Close the folder in VS Code by clicking File, then Close Folder.
Open your terminal and navigate to your Desktop by running:

cd ~/Desktop

Delete the project folder (replace the folder name with whatever you named yours):

rm -rf your-project-folder-name

On Windows

Use this command in PowerShell instead:

Remove-Item -Recurse -Force your-project-folder-name

Confirm the folder is gone by running ls and checking that your project folder no longer appears in the output.

Nice Work!

You just built a complete workspace template that makes Claude Code immediately effective on any project. These documents are your reusable foundation for communicating intent to AI coding agents.

Here's what you accomplished:

Created a production-ready CLAUDE.md that gives Claude Code full project context at the start of every session.
Built a custom SKILL.md that extends Claude Code with a reusable code-review workflow you can invoke on demand.
Wrote a SPEC document with clear boundaries and verifiable deliverables, and connected it to the IDD, SDD, and Harness methodology that ties your entire AI-assisted development workflow together.
Secret Mission: Executed a full IDD hierarchy from Product down to working code, proving you can communicate intent to AI agents clearly enough for autonomous execution.

Ready to quiz yourself?