open/claude-code-claude-md
1
0
Fork 0
Code Activity Actions

feat: initial companion repo for CC-010 CLAUDE.md

Browse source
This commit is contained in:
Kjell Tore Guttormsen 2026-03-30 10:38:01 +02:00
commit 5e4ce5781e
5 changed files with 719 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

124
exercises/01-write-your-first.md Normal file
View file

@ -0,0 +1,124 @@
# Exercise 01: Write Your First CLAUDE.md
**Concept:** CLAUDE.md (CC-010)
**Level:** Basic
**Time:** ~10 minutes
---
## Objective
Write a CLAUDE.md for a real project you own. By the end of this exercise,
Claude will know who you are, what the project does, and how you want it
to behave -- automatically, every session.
This is your first hands-on contact with CLAUDE.md. The only requirement
is that you have a project directory with a few files in it.
---
## Before You Start
Confirm you have:
- [ ] Claude Code installed (`claude --version` prints a version)
- [ ] A project directory you want to write a CLAUDE.md for
- [ ] Claude Code open in that project directory
This exercise works best in your own project. If you do not have one
handy, open Claude Code in any directory that has at least a few files.
---
## Instructions
**Step 1:** Navigate to your project and open Claude Code.
```bash
cd /path/to/your-project
claude
```
Confirm there is no CLAUDE.md there yet:
```bash
ls CLAUDE.md
```
Expected output: `ls: CLAUDE.md: No such file or directory`
If a CLAUDE.md already exists, pick a different project for this exercise
or rename the existing one temporarily (`mv CLAUDE.md CLAUDE.md.bak`).
**Step 2:** Think about three things before you run anything.
- Who you are and what you care about when working on this project
- What the project does in one sentence
- Two or three rules that would save time if Claude knew them up front
(examples: "always use TypeScript", "never modify files in dist/", "prefer short functions")
You do not need to write these down. Just have them in mind.
**Step 3:** Paste this prompt into Claude Code:
```
Look at this project. Read the files here, then write a CLAUDE.md for it.
The CLAUDE.md should include:
1. What this project is (one short paragraph, 2-3 sentences max)
2. How to work on it (language, framework, any tools)
3. Three specific rules I want you to follow in every session
For rule 3, use these rules I care about:
- [replace this with your first rule, e.g. "Never use var, always use const or let"]
- [replace this with your second rule, e.g. "All functions must have a JSDoc comment"]
- [replace this with your third rule, e.g. "Do not modify package.json without asking first"]
Keep it under 60 lines. No headers longer than one line. Plain and direct.
```
Replace the three placeholder rules with your own before pasting.
**Step 4:** Review what Claude writes and ask for one change.
Read the CLAUDE.md Claude produced. Find one thing that is off, vague, or
missing, then ask Claude to fix it:
```
Change [the part that is wrong] to [what it should say].
```
This is a normal part of the process. CLAUDE.md files are written with
Claude, not entirely by it.
---
## Expected Output
After completing the steps above, you should see:
- A `CLAUDE.md` file in your project root
- It has a project description (not generic -- specific to your project)
- It has your three rules stated clearly
- It is under 60 lines total
If Claude produced something generic or padded, ask it to be more specific
and shorter. Generic CLAUDE.md files provide almost no value.
---
## What You Learned
- **CLAUDE.md is a briefing, not a manual:** Give Claude the context it needs
to behave like a new colleague who already knows your project
- **It is auto-loaded every session:** You never have to paste it in or say
"remember, we use TypeScript" again
- **Write it with Claude, not for Claude:** Use Claude to read the project
and draft the file, then you correct and sharpen it
---
## Next
Ready to see how CLAUDE.md files stack on top of each other? Move to
[Exercise 02: Hierarchy in Action](./02-hierarchy-in-action.md).

169
exercises/02-hierarchy-in-action.md Normal file
View file

@ -0,0 +1,169 @@
# Exercise 02: Hierarchy in Action
**Concept:** CLAUDE.md (CC-010)
**Level:** Intermediate
**Time:** ~15 minutes
---
## Objective
See how global, project, and subdirectory CLAUDE.md files work together.
Claude reads all three and applies them simultaneously, with more specific
files taking precedence over broader ones.
Exercise 01 covered a single CLAUDE.md. This exercise shows the full stack.
---
## Before You Start
Confirm you have:
- [ ] Completed Exercise 01 (or understand what CLAUDE.md does)
- [ ] Claude Code open in this repo directory
**Important:** This exercise creates a file at `~/.claude/CLAUDE.md`, which
is your global Claude Code configuration. If you already have one, back it up first:
```bash
cp ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.bak
```
Restore it after the exercise with:
```bash
mv ~/.claude/CLAUDE.md.bak ~/.claude/CLAUDE.md
```
---
## Instructions
**Step 1:** Create a global CLAUDE.md with a personal preference.
This file applies to every project you open with Claude Code, everywhere.
```bash
mkdir -p ~/.claude
```
Then paste this prompt into Claude Code:
```
Create a file at ~/.claude/CLAUDE.md with exactly this content:
# Global Preferences
Always respond in British English. Use "colour" not "color",
"organise" not "organize", "realise" not "realize".
When writing prose, prefer shorter sentences.
```
**Step 2:** Create a project-level CLAUDE.md with a project rule.
This file applies only when Claude Code is open in this directory.
Paste this prompt:
```
Create a CLAUDE.md in the current directory (not ~/.claude/) with exactly this content:
# Project Rules
Language: TypeScript only. No JavaScript files.
Indentation: 2 spaces. No tabs.
Imports: named imports preferred over default imports.
```
**Step 3:** Create a subdirectory CLAUDE.md with test-specific rules.
```bash
mkdir -p tests
```
Then paste:
```
Create a file at tests/CLAUDE.md with exactly this content:
# Test Rules
Test framework: vitest only.
Pattern: describe/it blocks with descriptive names.
Assertions: use expect() with .toBe(), .toEqual(), or .toThrow().
No jest, no mocha, no chai.
```
**Step 4:** Ask Claude to create a function and a test, then observe.
Paste this prompt:
```
Write a TypeScript function called formatDate that takes a Date object
and returns a string in the format "DD Month YYYY" (e.g. "04 April 2025").
Then write a vitest test for it in tests/formatDate.test.ts.
```
Watch the output carefully. Claude should:
- Use TypeScript (project rule)
- Use 2-space indentation (project rule)
- Use named imports (project rule)
- Use vitest with describe/it (test rule)
- Write in British English where prose appears (global rule)
---
## Expected Output
After completing all four steps, you should see:
- A `formatDate.ts` file using TypeScript, 2-space indentation, named imports
- A `tests/formatDate.test.ts` file using vitest, describe/it pattern
- Any comments or prose Claude writes use British English spellings
- Claude did not ask which framework to use or what indentation to apply
**How you know hierarchy worked:**
All three levels applied at once. The test file followed both the project
rules (TypeScript, 2-space) AND the test-specific rules (vitest, describe/it).
The global preference (British English) applied throughout.
---
## What You Learned
- **Global scope:** `~/.claude/CLAUDE.md` applies to every project
- **Project scope:** `./CLAUDE.md` applies only in the current directory
- **Subdirectory scope:** `tests/CLAUDE.md` applies only when working in `tests/`
- **More specific overrides broader:** If a test-specific rule conflicts with
a project rule, the test-specific rule wins inside `tests/`
- **All levels apply simultaneously:** Claude does not choose one level.
It reads all of them and follows all of them
---
## Clean Up
```bash
rm -f CLAUDE.md formatDate.ts tests/CLAUDE.md tests/formatDate.test.ts
rmdir tests 2>/dev/null || true
```
And if you backed up your global CLAUDE.md:
```bash
mv ~/.claude/CLAUDE.md.bak ~/.claude/CLAUDE.md
```
Or remove the test global file if you created a fresh one:
```bash
rm ~/.claude/CLAUDE.md
```
---
## Next
Ready to take a bad CLAUDE.md and make it effective? Move to
[Exercise 03: Audit and Improve](./03-audit-and-improve.md).

316
exercises/03-audit-and-improve.md Normal file
View file

@ -0,0 +1,316 @@
# Exercise 03: Audit and Improve
**Concept:** CLAUDE.md (CC-010)
**Level:** Advanced
**Time:** ~20 minutes
---
## Objective
Take a deliberately bad CLAUDE.md, identify what makes it ineffective,
and rewrite it so Claude actually follows it. This is the skill you will
use on every CLAUDE.md you inherit or write in a hurry.
---
## Before You Start
Confirm you have:
- [ ] Completed Exercises 01 and 02
- [ ] Claude Code open in this repo directory
---
## The Scenario
Your team has been using Claude Code for a few months. Someone wrote
a CLAUDE.md at the start and nobody has touched it since. It has grown.
It has contradictions. Claude seems to ignore half of it.
Your job: audit it, identify the problems, and rewrite it.
---
## The Bad CLAUDE.md
Read this carefully before you do anything. This is the file you are going to fix.
```markdown
# Project Instructions for Claude
## Overview
This is a very important web application project. Please make sure you
understand the full context before making any changes. We use modern
web technologies and follow industry best practices throughout the
entire codebase.
## General Coding Guidelines
- Write good code
- Make sure the code is clean and readable
- Follow best practices
- Use meaningful variable names
- Keep functions small and focused
- Add comments where necessary
- Make sure everything works correctly
- Handle errors properly
- Write tests for everything
- Make sure the UI looks good
## JavaScript Guidelines
- Use JavaScript for all frontend code
- Always use TypeScript for all files
- Use ES6+ features
- Avoid using var
- Use const and let appropriately
- Always use semicolons
- Never use semicolons
- Use 2-space indentation
- Use 4-space indentation
- Keep lines under 80 characters
- Keep lines under 120 characters
## Naming Conventions
- Use camelCase for variables and functions
- Use PascalCase for components and classes
- Use UPPER_SNAKE_CASE for constants
- Use kebab-case for file names
- Use camelCase for file names
- Use descriptive names that explain the purpose
## React Guidelines
- Use functional components with hooks
- Avoid class components unless absolutely necessary
- Use useState for local state
- Use useContext for global state
- Never use Redux
- Always use Redux for complex state management
- Use React Query for data fetching
- Keep components small, ideally under 50 lines
- Extract logic into custom hooks
- Always test components with React Testing Library
- Use Enzyme for component testing
- Never use Enzyme
## API and Backend
- Use REST APIs
- Use GraphQL for all API calls
- Document all API endpoints
- Return consistent error formats
- Use async/await everywhere
- Use promises instead of async/await for compatibility
## Testing
- Write unit tests for all utility functions
- Write integration tests for API routes
- Write end-to-end tests for critical user flows
- Use Jest for all tests
- Use Vitest instead of Jest
- Aim for 80% code coverage
- Tests should be fast
- Mock external dependencies
- Avoid mocking where possible, prefer real implementations
## Git Conventions
- Write meaningful commit messages
- Use conventional commits format
- Keep commits small and focused
- Always squash commits before merging
- Never squash commits, keep full history
- Branch names should describe the feature
## Performance
- Optimize for performance
- Avoid premature optimization
- Lazy load components where appropriate
- Use memoization when needed
## Security
- Never commit secrets
- Use environment variables for sensitive config
- Sanitize all user input
- Validate on both client and server
- Use HTTPS everywhere
- Keep dependencies updated
## Working With This Codebase
When I ask you to make changes, please consider all of the above
guidelines before writing any code. Also make sure to consider the
overall architecture and how your changes might affect other parts
of the system. Think about edge cases and error scenarios. Make sure
to write tests. Consider performance implications. Consider security
implications. Consider accessibility. Consider internationalization.
Consider browser compatibility. Make sure the code is maintainable.
Make sure other developers will understand it. Think about future
requirements that might affect your design decisions.
## Communication
- Be concise in your responses
- Explain what you are doing and why
- Ask clarifying questions when needed
- Provide examples when helpful
- Never make assumptions without confirming with me first
- Use your best judgment when requirements are unclear
- Always list every file you plan to change before making changes
- Summarize what you changed after each task
## Important Notes
- This project is actively developed by a team
- Always be careful with production code
- Make sure changes are backward compatible
- Consider the impact on existing users
- The tech lead has final say on architecture decisions
- Performance is a top priority
- Developer experience is equally important
- We value simplicity above all else
- We value completeness above all else
## Final Reminder
Remember to always follow all the guidelines above in every interaction.
Make sure your output is high quality and meets all the requirements
listed in this document. When in doubt, err on the side of caution and
ask before making significant changes.
```
---
## Your Task
**Step 1:** Read the bad CLAUDE.md above and make a list of the problems.
Before you ask Claude to help, identify the issues yourself. Look for:
- Instructions that are too vague to follow (what does "write good code" tell Claude?)
- Contradictions (two rules that say opposite things)
- Duplicate intent in different sections
- Length: CLAUDE.md files over 200 lines see reduced adherence
Write your list. You do not need Claude for this step.
**Step 2:** Ask Claude to audit it and list the issues.
Paste this prompt into Claude Code:
```
Read the following CLAUDE.md file and list every problem you find.
For each problem, state:
1. What the problem is
2. Why it reduces effectiveness
3. What the fix is
Focus on: vague instructions, contradictions, redundancy, and length.
Do not rewrite it yet. Just audit.
[paste the full bad CLAUDE.md from the exercise here]
```
Compare Claude's audit to your own list. Did Claude find anything you missed?
**Step 3:** Rewrite it.
Now ask Claude to produce the improved version:
```
Rewrite this CLAUDE.md to fix all the problems you identified.
Rules for the rewrite:
- Under 80 lines total
- Every instruction must be specific and verifiable
(Claude should be able to check "did I do this?" after each task)
- No contradictions -- pick one option where the original was ambiguous
- No vague language: "write good code" is not an instruction
- Remove anything that duplicates another rule
- Assume the project uses TypeScript, React with hooks, Vitest for tests,
conventional commits, REST APIs, and 2-space indentation
Output only the rewritten CLAUDE.md. No commentary.
```
**Step 4:** Evaluate the result against the success criteria below.
---
## Success Criteria
Check each item:
- [ ] Under 80 lines (count them)
- [ ] Every rule is specific: you could look at code and say "yes, this follows the rule" or "no, it does not"
- [ ] No contradictions remain (JavaScript vs TypeScript, semicolons vs no semicolons, etc.)
- [ ] No vague instructions ("write good code", "follow best practices" removed)
- [ ] A developer reading it for the first time would know exactly what to do
If any item fails, paste the rewrite back to Claude and point out the
specific problem. One round of revision is normal.
---
## Reference: Problems in the Original
Here is what to look for if you want to check your own audit:
**Contradictions (7 pairs):**
- JavaScript for all frontend vs TypeScript for all files
- Always use semicolons vs never use semicolons
- 2-space indentation vs 4-space indentation
- Lines under 80 characters vs lines under 120 characters
- Never use Redux vs always use Redux for complex state
- Use Jest vs use Vitest
- Squash commits vs never squash commits
**Vague instructions (examples):**
- "Write good code"
- "Make sure everything works correctly"
- "Write meaningful commit messages"
- "Optimize for performance"
- "Be careful with production code"
**Redundancy:**
- The final "Working With This Codebase" section repeats most of the earlier sections
- The "Final Reminder" adds no new information
- Performance appears in at least three sections
**Length:**
- The original is over 200 lines. Research on CLAUDE.md adherence shows
that shorter files with specific rules outperform long files with vague ones.
Claude is more likely to follow 20 specific rules than 200 vague ones.
---
## What You Learned
- **Specific beats vague:** "Use const and let, never var" is a rule Claude can follow.
"Write good code" is not
- **Contradictions disable rules:** When two instructions conflict, Claude may follow
neither rather than guess which one you meant
- **Length reduces adherence:** A 200-line CLAUDE.md is not twice as effective as a
100-line one. It is less effective. Keep it under 100 lines when possible
- **Audit before you ship:** A five-minute audit of any CLAUDE.md catches most of the
problems that would otherwise waste hours of back-and-forth
---
## What Comes Next
You now understand CLAUDE.md completely: how to write one from scratch
(Exercise 01), how the hierarchy works (Exercise 02), and how to audit
and improve an existing one (Exercise 03).
Next concepts to explore:
- **CC-006 Permissions** - Control what Claude Code is allowed to do
- **CC-012 Hooks** - Automate actions that trigger before or after Claude acts
- **CC-005 Custom Commands** - Create slash commands Claude runs on demand