Architect-First Dev with Claude Code

Build a task dashboard using structured Claude Code workflows and specs.

Introduction

30 Second Summary

You have probably asked an AI coding assistant to build something, only to get back code that works but looks nothing like what you would have written. Different naming conventions, unnecessary frameworks, a file structure you would never choose.

In this project, you will build the same app twice with Claude Code. First with a vague prompt, then with structured architectural guidance, so you see firsthand why the process matters more than the prompt.

What You'll Build

You will start a Claude Code session, describe a feature, and watch Claude build it following your exact conventions on the first pass.

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

A structured project setup with CLAUDE.md and SPEC.md that makes every future Claude Code session produce architecturally consistent code. No more re-explaining your standards from scratch.
Path-scoped rules that automatically enforce your frontend and data layer conventions only when Claude touches those specific files, keeping your sessions lean and your code consistent.
A working task dashboard you can open in your browser, add tasks, filter by status, and refresh to see data persist across page reloads.
Secret Mission: Create a custom skill that packages a reusable "add a new feature" workflow you can trigger with a slash command.

Are there any prerequisites?

You need a Claude Pro or Max subscription and VS Code installed. This project assumes you have experience with web development and have used Claude Code before.

Before We Start

Before we dive in, let's lock in what you're about to build and why it matters. You're building a structured Claude Code workflow that produces architecturally consistent results, and a task dashboard is how you'll prove it works.

Set Up Your Project Workspace

Claude Code tracks every change it makes to your code through Git checkpoints. Without a git-initialized project directory, Claude Code cannot save snapshots, rewind mistakes, or track its own work.

In this step, you will verify your tools are ready, create your project folder, and confirm Claude Code launches correctly.

In this step, get ready to:

Verify Claude Code and Git for Windows are installed.
Create a git-initialized project directory with a .gitignore file.
Launch Claude Code and confirm it is interactive.

Verify Claude Code is installed and up to date

You need two tools ready before building anything: Claude Code for AI-assisted development, and Git for Windows so Claude Code can use the Bash tool for file operations.

Press the Windows key to open your search bar.
Type PowerShell and press Enter to open it.
Check if Claude Code is installed by running this command:

claude --version

✔️ I see a version number

Claude Code is installed. Make sure you are on the latest version by running this command:

claude update

You should see a confirmation that Claude Code is up to date, or that an update was applied.

ⓧ Command not found

Claude Code is not installed yet. Install it by running this command in PowerShell:

irm https://claude.ai/install.ps1 | iex

After installation completes, close PowerShell and reopen it so the claude command becomes available.
Verify the installation succeeded by running:

claude --version

You should now see a version number printed.

Does Claude Code require a subscription?

Yes. Claude Code requires a Claude subscription (Pro, Max, Team, or Enterprise), a Claude Console account, or access through a supported cloud provider. This project assumes you already have an active subscription.

Now check if Git for Windows is installed. Git for Windows is recommended so Claude Code can use the Bash tool. Without it, Claude Code falls back to PowerShell as its shell tool.

Check if Git is installed by running this command:

git --version

✔️ I see a version number

Git is ready. You are all set to create your project directory.

ⓧ Command not found

Download Git for Windows from git-scm.com/downloads/win.
Run the installer and accept the default options.
After installation, close and reopen PowerShell.
Verify by running:

git --version

You should now see a version number like git version 2.x.x.

Create and initialize the project directory

Move to your Desktop by running this command:

cd ~/Desktop

Create your project folder and move into it by running these commands:

mkdir task-dashboard
cd task-dashboard

Initialize a Git repository by running:

git init

You should see a message like Initialized empty Git repository in ... confirming the repo was created.

Why initialize Git before writing any code?

Claude Code uses Git to track every change it makes to your files. It creates automatic checkpoints before modifying code, so you can rewind to any previous state if something goes wrong.

Without a Git repository, Claude Code loses its ability to snapshot and undo. Initializing Git first means safety nets are in place from the very start.

Next, you need a .gitignore file to tell Git which files to exclude from tracking.

Create the .gitignore file by running these commands:

echo node_modules > .gitignore
echo .DS_Store >> .gitignore

What do these entries mean?

The node_modules entry prevents Git from tracking installed packages, which can contain thousands of files. The .DS_Store entry excludes macOS system files that have no place in a project repository.

Confirm the file was created correctly by running:

cat .gitignore

You should see two lines printed: node_modules and .DS_Store.

✔️ Awesome, I've got everything!

Your .gitignore is ready. On to launching Claude Code.

ⓧ I'd like to double check the full code

Your .gitignore should contain exactly these two lines:

node_modules
.DS_Store

If the contents don't match, delete the file and recreate it by re-running the two echo commands above.

Seeing an error when creating .gitignore?

Make sure you are inside the task-dashboard folder. Run pwd to check your current directory.
If cat .gitignore shows extra blank lines or unexpected content, delete the file and try again. Run del .gitignore to remove it, then re-run both echo commands.

Why can't I create my .gitignore file?

Launch Claude Code and verify it works

Your project directory is ready. The final check is confirming that Claude Code can start an interactive session inside it.

Before you run the next command, what do you think Claude Code will show you when it starts? What information would a coding assistant need to display at the beginning of a session?

Launch Claude Code by running:

claude

The Claude Code interactive prompt appears, showing the version number, the current model (Sonnet 4.5), and your working directory (task-dashboard). This confirms Claude Code knows where it is and what it is working with.

Confirm the session is interactive by typing:

/help

You should see a list of available commands printed. This confirms Claude Code is responding to input.

What are Claude Code slash commands?

Slash commands like /help, /clear, and /exit are built-in controls that let you manage your Claude Code session. They are separate from the prompts you send to Claude.

You will use several of these throughout the project, including /init and /context in later steps.

Close the session by typing:

/exit

You are back in PowerShell, still inside the task-dashboard directory. Claude Code closed cleanly.

Claude Code not launching?

If you see a permission or authentication error, make sure you are signed in to your Claude account. Claude Code requires an active Pro, Max, Team, or Enterprise subscription.
If the claude command is not found, you may need to close PowerShell and reopen it so the PATH update takes effect.

Why won't Claude Code start in my terminal?

Your workspace is locked in. You have a git-tracked project directory, a clean .gitignore, and a working Claude Code installation. Next up, you will give Claude a deliberately vague prompt and see what it builds without any architectural guidance.

The Naive Build

Your project workspace is set up with a git-initialized directory and all your tools verified. Now comes the experiment.

What happens when you ask Claude Code to build something without telling it how you want it built? Claude makes every architectural decision on its own. You need to see what that produces before you can appreciate the difference structure makes.

In this step, get ready to:

Give Claude a vague prompt and let it build freely.
Audit the output for tech choices and patterns you disagree with.
Commit the result as a baseline snapshot for comparison.

Give Claude a vague prompt and let it build

You are going to hand Claude a deliberately vague prompt with zero guidance on tech stack, file structure, or coding standards. The goal is not to build the best dashboard. The goal is to observe what Claude decides when left to its own judgment.

Start a new Claude Code session by running this command in PowerShell:

claude

You should see the Claude Code interactive prompt appear with the version, model, and your working directory.

Not seeing the Claude Code prompt?

Make sure you are inside the task-dashboard directory. Run cd ~/Desktop/task-dashboard and try again.

If you see a login or subscription error, confirm your Claude Pro or Max subscription is active at claude.ai.

Help me troubleshoot launching Claude Code

Before you enter the next prompt, pause and predict. What tech stack do you think Claude will choose on its own? Will it pull in a framework? How many files will it create?

Copy and paste this deliberately vague prompt into the Claude Code session:

Build me a task management dashboard. It should let me add tasks, mark them complete, and filter by status. Make it look professional.

What is happening right now?

Claude is reading your prompt and making every decision on its own: which languages to use, whether to pull in a framework, how to name files, how to organize the code, and what patterns to follow.

Do not interrupt or correct it. Let it run to completion. The whole point is to see what unguided output looks like.

When Claude finishes building and returns to the prompt, exit the session by typing:

/exit

Check what files Claude created by running:

ls

You should see at least an index.html file, and likely additional JS and CSS files. Take note of how many files Claude created and how it organized them.

Open the generated dashboard in your browser by running:

start index.html

Different filename?

If Claude named the HTML file something other than index.html, use that filename in the start command instead.

Your browser opens with a working task dashboard. You can add tasks, mark them complete, and filter by status. It works. Keep the browser tab open for the next substep.

Audit what Claude produced

The dashboard works. That is not the question. The question is whether Claude's architectural decisions match what you would choose for a professional project.

Look at the file list from your earlier ls output. Did Claude pull in a framework you did not ask for? Did it create more files than necessary? Is the folder structure what you would have chosen?
Open the JavaScript files in VS Code. Check the code style: are variable names consistent? Is there unnecessary abstraction or over-engineering?
Note at least 3 things you would do differently. Think about tech choices, naming conventions, file organization, and code patterns.

Why does this matter?

Claude built something functional. That is a success. But functional code and architecturally consistent code are not the same thing.

Without guidance, Claude guesses at your preferences. It might pick Tailwind when you prefer vanilla CSS. It might create a utils.js you never asked for. It might use var where you always use const. Every one of those mismatches is rework you have to do later.

Commit the naive build as your baseline

This version is your "before" snapshot. You will compare it against the structured build you create later in the project.

Stage all the files Claude generated by running:

git add -A

Commit them with a descriptive message by running:

git commit -m "naive build: unstructured Claude Code output"

You should see Git confirm the commit with a list of the files that were added. This commit locks in the unguided version so you can always come back and compare.

Seeing a git config error?

If Git asks you to set your name and email before committing, run these two commands with your own details:

git config user.name "Your Name"
git config user.email "your@email.com"

Then run the git commit command again.

Help me fix my git commit error

You now have proof of what Claude builds without architectural guidance. It works, but it does not match your standards. Next up, you will give Claude the context it needs to build things your way.

Write Your Architecture

The naive build proved something important. Claude Code produced a working app, but it guessed at your tech stack, your file structure, and your naming conventions.

In this step, you will give Claude the context it was missing. You will create a CLAUDE.md file that locks in your architectural decisions. Then you will use Claude's interview workflow to produce a detailed spec before a single line of code gets written.

In this step, get ready to:

Create a CLAUDE.md file with your chosen tech stack, code style, project structure, and architecture decisions.
Have Claude interview you to produce a complete SPEC.md with requirements, edge cases, and acceptance criteria.
Clean out the naive build files and commit your architecture artifacts.

Create your CLAUDE.md

CLAUDE.md is a project memory file that Claude Code loads at the start of every session. Whatever you write in it becomes Claude's persistent understanding of your project's architecture, tech stack, and coding standards.

Start a new Claude Code session by running this command in your PowerShell terminal:

claude

You should see the Claude Code interactive prompt appear with the version number, current model, and your task-dashboard working directory.

Generate a starter CLAUDE.md by running this command inside the Claude Code session:

/init

Claude analyzes your project files and generates a CLAUDE.md with build commands, detected conventions, and project structure details.

What does /init do?

/init scans your codebase and creates a starter CLAUDE.md based on what it finds. Since the naive build files are still here, Claude will detect whatever stack it chose in Step 2.

That is fine. You are about to replace the entire file with your own architectural decisions. The /init output is just scaffolding to start from.

The generated file is a starting point, not the final version. You need to replace it with your own rules so Claude builds the app your way.

Switch to VS Code and open the CLAUDE.md file that /init just created in your task-dashboard folder.
Select all the content in the file and delete it.
Paste the following as the start of your file. This defines your tech stack and code style rules:

# Task Dashboard

## Tech Stack
- Frontend: Vanilla HTML, CSS, JavaScript (no frameworks, no libraries)
- No build tools or bundlers
- Use ES modules syntax where supported, otherwise plain script tags
- Data persistence: localStorage only (no backend)

## Code Style
- JavaScript: camelCase for variables and functions, PascalCase for classes
- CSS: kebab-case for class names (e.g., task-card, filter-bar)
- HTML: semantic elements (main, section, article, header, footer, button)
- Keep functions under 30 lines
- Use const by default, let only when reassignment is needed
- No var

What do these sections do?

Tech Stack tells Claude to use vanilla HTML, CSS, and JS only. No frameworks, no build tools. This prevents Claude from pulling in React or Tailwind on its own.
Code Style locks in naming conventions. camelCase for JS, kebab-case for CSS, semantic HTML elements, and no var.

Continue by pasting the rest of the file directly below the Code Style section. This covers your project structure, architecture decisions, and workflow:

## Project Structure
```
/
├── index.html          # Single HTML entry point
├── css/
│   └── styles.css      # All styles in one file
├── js/
│   ├── app.js          # UI rendering and event handling
│   └── storage.js      # All localStorage operations
├── CLAUDE.md
└── SPEC.md
```

## Architecture Decisions
- Single-page application, no routing
- Component pattern: each UI section has a render function in app.js
- Storage module (storage.js) is the only file that touches localStorage
- app.js imports from storage.js, never accesses localStorage directly
- Tasks are stored as a JSON array in localStorage under the key "tasks"
- Each task has: id (timestamp), title, description, status (todo/in-progress/done), createdAt

## Workflow
- Test by opening index.html directly in the browser (no server needed)
- Verify localStorage in browser DevTools > Application > Local Storage
- Commit after each working feature with descriptive messages

What do these sections do?

Project Structure tells Claude exactly where files belong. storage.js handles all data operations. app.js handles UI rendering. No guessing required.
Architecture Decisions spells out the separation of concerns. Only storage.js touches localStorage. This prevents Claude from scattering data access across multiple files.
Workflow tells Claude how to test. Open the HTML file directly in the browser, no dev server needed.

Save CLAUDE.md.

Keep CLAUDE.md lean

Anthropic recommends keeping CLAUDE.md under 200 lines. Longer files consume more context and reduce adherence. For each line, ask: "Would removing this cause Claude to make a mistake?" If not, cut it.

✔️ Awesome, I've got everything!

Great. Make sure you have saved CLAUDE.md in VS Code before continuing.

ⓧ I'd like to double check the full code

Your CLAUDE.md should contain both chunks you pasted above, in order. Scroll up and confirm you have all five sections:

The heading # Task Dashboard at the very top.
## Tech Stack with four bullet points.
## Code Style with six bullet points.
## Project Structure with the file tree showing index.html, css/, js/, CLAUDE.md, and SPEC.md.
## Architecture Decisions with six bullet points.
## Workflow with three bullet points.

Now let's confirm Claude Code knows about your file. Before you run this next command, what do you think /context will show?

Switch back to your Claude Code session and run this command:

/context

You should see CLAUDE.md listed under Memory files. This confirms Claude knows your architectural rules exist and will reference them.

CLAUDE.md not showing in /context?

Make sure CLAUDE.md is saved in the root of your task-dashboard folder, not inside a subfolder.
Check the filename is exactly CLAUDE.md (all caps, with the .md extension).
Try exiting the session with /exit and starting a fresh one with claude. CLAUDE.md loads at session start, so a new session picks up any changes.

Why isn't my CLAUDE.md showing in the /context output?

Have Claude interview you for a spec

Your CLAUDE.md tells Claude how to build. A spec tells Claude what to build. Instead of writing the spec yourself and hoping you covered every edge case, you can have Claude interview you to surface the requirements you might not have thought of.

In the same Claude Code session, paste this prompt:

I want to build a task management dashboard. Interview me in detail using the AskUserQuestion tool. Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered. Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.

Why have Claude interview you?

Anthropic's engineering teams recommend this interview workflow for any feature bigger than a quick fix. Claude asks about things you would not think to specify upfront: what happens when localStorage is full, how should empty states look, what fields does each task need.

The result is a spec that captures edge cases and tradeoffs before implementation starts. This prevents the "oh wait, I didn't think about that" rewrites that eat up time.

Claude will ask you a series of questions one at a time. Answer honestly based on what you want the dashboard to do.

Answering the interview

Claude will ask about task fields, filtering behavior, data persistence, UI layout, error handling, and more. There are no wrong answers. Just describe what you want the finished dashboard to look and feel like.

When Claude finishes interviewing, it writes the complete spec to SPEC.md.

Switch to VS Code and open SPEC.md in your task-dashboard folder.
Review the spec. A good spec names the files involved, states what is in scope and out of scope, and ends with acceptance criteria that prove the feature works.

What makes a good spec?

The most useful specs are self-contained. They name the files and interfaces involved, state what is out of scope, and end with an end-to-end verification step that proves the feature works.

If your SPEC.md is missing any of these, you can ask Claude to fill in the gaps before moving on.

Claude skipped the interview and went straight to writing code?

This can happen if Claude misinterprets the prompt. Type "Stop. I asked you to interview me first, not write code. Please start asking me questions about the task dashboard requirements." Claude will switch to interview mode.
If Claude already wrote files, press Esc twice to open the rewind menu and restore the previous state before trying the prompt again.

Claude skipped the interview and started writing code. How do I get it to interview me first?

Commit your architecture artifacts

Your architecture is defined. Now clean out the leftover naive build files so the next step starts from a clean slate with only your architectural foundation.

In VS Code's Explorer sidebar, delete all files and folders from the naive build. Keep only CLAUDE.md, SPEC.md, and .gitignore.
Right-click each file or folder you want to remove and select Delete.

Open a new terminal in VS Code by pressing Ctrl+` (backtick key).
Stage and commit your architecture files by running these commands:

git add -A
git commit -m "architecture: add CLAUDE.md and SPEC.md"

What does this commit do?

git add -A stages everything, including the deleted naive build files. The commit captures a clean state with only your architectural foundation: CLAUDE.md, SPEC.md, and .gitignore.

You should see a commit summary listing the deleted files and the two new files. These two files are now your project's architectural foundation.

Seeing 'nothing to commit'?

Make sure you saved both CLAUDE.md and SPEC.md in VS Code before running the commit.
Confirm you are in the task-dashboard directory by running pwd in the terminal.

My git commit says nothing to commit. How do I fix this?

You now have two commits in your git history: the naive build and the architecture. In the next step, you will start a fresh Claude Code session, hand it your CLAUDE.md and SPEC.md, and watch it build the exact same app following your rules this time.

The Structured Build

Your project now has an architectural foundation. CLAUDE.md defines your conventions and SPEC.md captures every requirement and edge case.

In this step, you will start a fresh Claude Code session and give Claude a focused implementation prompt. With architecture and requirements already defined, Claude can build the entire dashboard following your exact standards.

In this step, get ready to:

Start a fresh Claude Code session and build the dashboard from your spec.
Test the app in the browser and compare the result to the naive build.

Start a fresh session and build from the spec

Starting a fresh session gives Claude clean context focused entirely on implementation. The previous session's conversation history would add noise, so a new session loads CLAUDE.md automatically and starts with a blank slate.

Close the current Claude Code session by running this command:

/exit

Start a fresh session by running:

claude

You should see the Claude Code prompt appear with the version number, the current model (Sonnet 4.5), and your task-dashboard working directory.

Verify that CLAUDE.md loaded into the session by running:

/context

You should see CLAUDE.md listed under Memory files in the output. This confirms Claude knows your tech stack, code style, and file structure before you ask it to build anything.

Don't see CLAUDE.md in the output?

Make sure you are in the task-dashboard directory. Run pwd in a separate PowerShell window to confirm.
Check that CLAUDE.md exists in the folder by running ls in PowerShell. If it is missing, revisit the previous step to recreate it.
help me figure out why Claude Code is not loading my CLAUDE.md file

Paste this implementation prompt into the Claude Code session:

Read SPEC.md and implement the task dashboard following the spec exactly. Use the tech stack and patterns defined in CLAUDE.md. Build incrementally: start with the HTML structure, then add styling, then implement the JavaScript. Run through the acceptance criteria in the spec when done.

What does this prompt do?

"Read SPEC.md" tells Claude to start by understanding the full requirements before writing any code.
"Use the tech stack and patterns defined in CLAUDE.md" anchors Claude to your architectural decisions instead of picking its own.
"Build incrementally" breaks the task into phases so Claude does not try to generate everything in one shot.
"Run through the acceptance criteria" makes Claude self-test against your spec before declaring the build complete.

Let Claude work through the build without interrupting. Watch how it references your CLAUDE.md conventions and follows the file structure you specified.

What is happening while Claude builds?

Claude reads both SPEC.md and CLAUDE.md before generating any files. It creates the project structure from your architecture decisions, not its own defaults.

You should see Claude creating index.html, css/styles.css, js/app.js, and js/storage.js. These match the exact project structure in your CLAUDE.md.

Verify the structured build

Claude has finished building. Now you need to see the result for yourself and compare it to the naive version from Step 2.

Close the Claude Code session by running:

/exit

You are about to open another task dashboard built by Claude. Before you do, what do you expect to see differently this time compared to the naive build?

Open index.html in your browser by running:

start index.html

Add a new task using the form on the page.
Mark a task as complete.
Use the filter to show only completed tasks.
Refresh the page to confirm your tasks persist across page reloads.

Your dashboard should let you add tasks, complete them, and filter by status. Refreshing the page keeps your tasks intact because they are stored in localStorage.

How does this compare to the naive build?

Switch to VS Code and look at the files Claude created. Here is what to look for:

The file structure should match your CLAUDE.md specification: index.html, css/styles.css, js/app.js, and js/storage.js.
All localStorage operations should live in js/storage.js only. The naive build likely scattered storage calls across multiple files.
Variable names in js/app.js should use camelCase and CSS classes in css/styles.css should use kebab-case, matching your code style rules.
The HTML should use semantic elements like main, section, and article instead of generic div wrappers.

Same app, dramatically different quality. That is the power of giving Claude proper architectural context.

App not working as expected?

If start index.html opens a blank page, check that index.html exists in your task-dashboard directory by running ls in PowerShell.
If tasks disappear after refreshing, press F12 to open DevTools, click Application, then expand Local Storage. Confirm you see a tasks key with your data.
If Claude used a framework despite your conventions, start a new claude session, type /rewind to restore the previous state, and re-enter the prompt with stronger emphasis on no frameworks.
help me debug my structured Claude Code build

Save this version by running these commands:

git add -A
git commit -m "feat: structured task dashboard build"

You should see a commit summary listing the new files Claude created.

Your dashboard works and follows your exact architectural standards. Next up, you will create path-scoped rules that give Claude targeted guidance for specific file types, keeping context lean and conventions tight.

Lock In Patterns with Path-Scoped Rules

Your structured build proved that CLAUDE.md transforms Claude's output into code that matches your standards. Now it's time to make that guidance even more precise.

Right now, every rule in CLAUDE.md loads for every file, even when it's irrelevant. Your frontend accessibility rules don't need to consume context when Claude is editing storage.js. Path-scoped rules solve this by activating only for matching files.

In this step, get ready to:

Create path-scoped rules for frontend files.
Create path-scoped rules for the data layer.
Test the rules by having Claude add a new feature.

Create frontend-specific rules

The .claude/rules/ directory holds Markdown files that Claude Code discovers automatically. Each rule file can include YAML frontmatter with a paths field that tells Claude when to activate it.

In VS Code, look at the Explorer sidebar on the left.
Right-click on the task-dashboard project folder and select New Folder.
Type .claude and press Enter.
Right-click on the new .claude folder and select New Folder again.
Type rules and press Enter.
Right-click on the rules folder and select New File.
Type frontend.md and press Enter.
Paste the following content into frontend.md:

---
paths:
  - "*.html"
  - "css/**"
  - "js/app.js"
---

# Frontend Rules

- Use semantic HTML5 elements (section, article, header, nav, main), not generic divs
- CSS: mobile-first approach, use CSS custom properties for colors and spacing
- JavaScript: no inline event handlers in HTML, always use addEventListener in app.js
- Accessibility: all interactive elements must have visible focus styles and appropriate aria labels
- Forms: prevent default submission, validate input before processing
- Use template literals for building HTML strings in JavaScript

What do these rules do?

The paths frontmatter at the top is the key. It tells Claude Code to apply these rules only when working on HTML files, CSS files, and app.js.

When Claude edits storage.js, these rules stay out of context entirely. That means less noise and better adherence to the rules that actually matter for the file Claude is touching.

Save frontend.md by pressing Ctrl+S.
Confirm frontend.md appears inside the .claude/rules/ folder in the Explorer sidebar.

Don't see the .claude folder?

Some file explorers hide folders that start with a dot. In VS Code, the Explorer sidebar shows dotfiles by default. If you still don't see it, check that you created the folder inside task-dashboard, not one level above it.

help me find the .claude folder I just created

Create data layer rules

Your storage module needs its own targeted guidance. These rules reinforce that storage.js is the single point of access for localStorage and must handle data corruption gracefully.

Right-click on the rules folder in the Explorer sidebar and select New File.
Type data-layer.md and press Enter.
Paste the following content into data-layer.md:

---
paths:
  - "js/storage.js"
---

# Data Layer Rules

- This is the ONLY file that may access localStorage
- Every function must validate its input before saving
- Wrap JSON.parse calls in try/catch to handle corrupted data gracefully
- If localStorage data is corrupted, reset to an empty array and log a warning to the console
- Export all functions so app.js can import them
- Never import from app.js (storage.js has no UI dependencies)

What do these rules do?

The paths frontmatter scopes these rules to js/storage.js only. Claude will follow these rules when editing the storage module, but ignore them everywhere else.

The rules reinforce architectural boundaries you set in CLAUDE.md. They ensure storage.js stays independent from the UI, validates inputs, and never lets corrupted localStorage data crash the app.

Save data-layer.md by pressing Ctrl+S.
Confirm both frontend.md and data-layer.md appear inside .claude/rules/ in the Explorer sidebar.

Only see one file in the rules folder?

Make sure you created data-layer.md inside the rules folder, not inside .claude directly. Click on the rules folder to expand it and check that both files are listed there.

help me check that my .claude/rules files are in the right place

Why path-scoped rules instead of more CLAUDE.md lines?

Every line in CLAUDE.md loads into Claude's context window at the start of every session, consuming tokens. Path-scoped rules only load when Claude reads a file that matches the paths pattern.

This keeps your context budget lean. As your project grows, targeted rules scale much better than cramming everything into one file.

Test the rules in action

Your rules exist on disk, but you need to verify Claude actually picks them up. The best test is to ask Claude to add a real feature and watch whether it follows your targeted rules.

Open VS Code's integrated terminal by pressing Ctrl+` (backtick) if it's not already visible.
Start a new Claude Code session by running:

claude

Before you check the context, think about this: will Claude show both rule files immediately, or will they only appear once Claude touches a matching file?

Run the following command inside the Claude Code session:

/context

You should see CLAUDE.md listed under Memory files, along with your two rule files from .claude/rules/. Claude Code discovers all rule files in the directory automatically.

Why do the rules appear before Claude touches any matching files?

Claude Code discovers all .md files in .claude/rules/ recursively at session start. Path-scoped rules only activate and enter the context window when Claude reads a file that matches their paths pattern. So /context lists them as available, but they won't consume context until Claude works on a matching file.

Now for the real test. You'll ask Claude to add a priority feature and watch whether it follows both your CLAUDE.md conventions and the path-scoped rules.

Enter the following prompt in your Claude Code session:

Add a task priority feature (high, medium, low) with a colored indicator. Let me filter by priority too.

What to watch for while Claude builds

Pay attention to Claude's choices as it works. When it edits index.html and app.js, the frontend rules activate. You should see semantic HTML elements, addEventListener usage, and template literals.

When it edits storage.js, the data layer rules activate. Watch for input validation and the storage module staying independent from the UI.

Wait for Claude to finish building the priority feature.
Open index.html in your browser.

Do you think the priority feature will work on the first try? What do you expect to see when you add a task with a priority level?

Add a task and set its priority to high.
Add another task and set its priority to low.
Use the priority filter to show only high-priority tasks.
Refresh the page to confirm tasks persist across reloads.

You should see colored priority indicators on each task card and a working filter that narrows the list by priority level. Tasks should survive a page refresh thanks to localStorage persistence.

Commit the new feature by running these commands in a separate terminal (not inside Claude Code):

git add -A
git commit -m "feat: task priority with path-scoped rules"

Priority feature not working as expected?

If the colored indicators are missing or the filter doesn't work, Claude may not have followed your path-scoped rules. Check app.js for inline event handlers (which your frontend rules prohibit) or direct localStorage access (which your data layer rules prohibit).

If Claude built something that ignores the rules, you can rewind with /rewind in the Claude Code session and re-prompt. Mention the specific rule it missed.

help me debug why Claude didn't follow my path-scoped rules

Your project now has layered guidance: CLAUDE.md for project-wide standards, and path-scoped rules for file-specific conventions. Next up, you'll take this even further by packaging a reusable workflow into a custom skill.

Secret mission

Create a Custom Skill

You have set up CLAUDE.md, a detailed spec, and path-scoped rules. But every time you want to add a new feature, you still have to remember the right workflow. What if you could package that entire process into a single slash command?

Clean Up Your Resources

This project runs entirely locally with no cloud resources, so there are no ongoing costs beyond your existing Claude subscription. Decide whether to keep your resources running, pause them to come back later, or delete them entirely.

Resources you used:

task-dashboard project directory on your Desktop (includes CLAUDE.md, SPEC.md, .claude/rules/, .claude/skills/, and all app code).
Browser localStorage data (task entries stored under the "tasks" key).
Git repository history (commits from the naive build, architecture, structured build, priority feature, and due dates).

Keep everything running

No action needed. Choose this if you are still actively building on the task dashboard or want to keep your Claude Code configuration files as a reference for future projects.

Your task-dashboard folder stays on your Desktop with all files intact.
Your CLAUDE.md, path-scoped rules, and custom skill are ready to use in your next Claude Code session.
You can reopen the project anytime by running claude from inside the task-dashboard directory.

Pause - I'll come back to this later

Close running processes to free up system resources. Your project files stay on disk so you can pick up where you left off.

Exit your Claude Code session by typing /exit or pressing Ctrl+D twice.
Close the task-dashboard folder in VS Code.
When you come back, open the task-dashboard folder in your terminal and run claude to start a new session. Claude Code automatically loads your CLAUDE.md and rules.

Delete - I don't want to use this again

Remove all project files and stored data. This cannot be undone.

Exit your Claude Code session by typing /exit if it is still open.
Close the task-dashboard folder in VS Code.
Delete the project directory. On macOS/Linux, run:

cd ~/Desktop
rm -rf task-dashboard

On Windows (PowerShell), run:

cd ~\Desktop
Remove-Item -Recurse -Force task-dashboard

Clear the task data from your browser. Open the browser you used to test the dashboard, press F12 to open DevTools, go to the Application tab, expand Local Storage, right-click the entry for your file, and select Clear.

Nice Work!

Nice work! You have built a fully functional task dashboard with Claude Code, and more importantly, you now own a repeatable process for getting architecturally consistent results from every AI-assisted build.

You've learned how to:

Experience the contrast between a vague-prompt build and a structured, spec-driven build, so you know exactly why giving Claude architectural context produces dramatically better results.
Create a CLAUDE.md for persistent project memory and use Claude's interview workflow to produce a detailed SPEC.md before writing a single line of code.
Add path-scoped rules in .claude/rules/ that enforce targeted conventions for frontend and data layer code only when Claude touches matching files.
Secret Mission: Create a custom skill that packages a reusable "add a new feature" workflow you can trigger with a slash command.

Ready to quiz yourself?