From 5e4ce5781e8eade635e9c839980c3b74de878e86 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Mon, 30 Mar 2026 10:38:01 +0200 Subject: [PATCH] feat: initial companion repo for CC-010 CLAUDE.md --- CLAUDE.md | 40 ++++ README.md | 70 ++++++ exercises/01-write-your-first.md | 124 +++++++++++ exercises/02-hierarchy-in-action.md | 169 +++++++++++++++ exercises/03-audit-and-improve.md | 316 ++++++++++++++++++++++++++++ 5 files changed, 719 insertions(+) create mode 100644 CLAUDE.md create mode 100644 README.md create mode 100644 exercises/01-write-your-first.md create mode 100644 exercises/02-hierarchy-in-action.md create mode 100644 exercises/03-audit-and-improve.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..280fef9 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,40 @@ +# CLAUDE.md: Give Claude Code Standing Instructions + +## What this project is + +A companion repo for the From AI to Chitta article on **CLAUDE.md** +(concept ID: `CC-010`). It contains exercises that let you write, +layer, and improve CLAUDE.md files in your own projects. + +Article: https://fromaitochitta.com/claude-code-claude-md + +## How to use this + +1. Open Claude Code in this directory: `cd claude-code-claude-md && claude` +2. Work through exercises in order: `exercises/01-write-your-first.md`, then 02, then 03 +3. Each exercise has a self-contained prompt you paste into Claude Code +4. Compare your output to the expected output described in each exercise + +## Code quality expectations + +- This is a learning repo. Clarity over cleverness. +- Every exercise must run without modification on a clean clone +- No external dependencies unless explicitly listed in the exercise +- If something does not work as expected, that is useful information -- note it + +## Project structure + +``` +exercises/ Numbered exercises with prompts and expected output +CLAUDE.md This file -- project instructions +README.md Overview for anyone who clones this repo +``` + +## Domain + +Claude Code Memory and Instructions + +## Memory + +Keep session notes in a local `MEMORY.md` (gitignored). This file +(CLAUDE.md) is for instructions. MEMORY.md is for state. diff --git a/README.md b/README.md new file mode 100644 index 0000000..6a3bae2 --- /dev/null +++ b/README.md @@ -0,0 +1,70 @@ +# CLAUDE.md: Give Claude Code Standing Instructions + +Every time you open Claude Code, it starts fresh. It does not remember +your last session, your preferences, or your project's conventions. +CLAUDE.md fixes this. It is a plain text file Claude reads automatically +before doing anything, every single session. + +Companion repo for the article +[CLAUDE.md: Give Claude Code Standing Instructions](https://fromaitochitta.com/claude-code-claude-md) on From AI to Chitta. + +--- + +## What You Will Learn + +By working through the exercises in this repo, you will be able to: + +- Write an effective CLAUDE.md that gives Claude useful context about your project +- Use the global, project, and subdirectory hierarchy to scope instructions precisely +- Audit an existing CLAUDE.md and improve it so Claude actually follows it + +These are not theoretical outcomes. Complete the exercises and you will +have a CLAUDE.md in your own project that saves you time every session. + +## Prerequisites + +- Claude Code installed (`claude --version` prints a version) +- A project of your own you can practice on (any directory with a few files) +- Basic comfort with the terminal (cd, ls, opening files) + +No npm install, no Docker, no build step. + +## Exercises + +| # | Exercise | What It Covers | +|---|----------|---------------| +| 01 | [Write Your First CLAUDE.md](exercises/01-write-your-first.md) | Create a CLAUDE.md from scratch for a real project | +| 02 | [Hierarchy in Action](exercises/02-hierarchy-in-action.md) | Global, project, and subdirectory CLAUDE.md files working together | +| 03 | [Audit and Improve](exercises/03-audit-and-improve.md) | Diagnose a bad CLAUDE.md and rewrite it | + +Start at `exercises/01-write-your-first.md`. Each exercise links to the next. + +## How to Use This Repo + +**"Show me what it does":** Browse `exercises/` and read through +the prompts. Understand the pattern before you run anything. + +**"Let me actually do it":** Open Claude Code in this directory +and follow the exercises in order. Each one has an expected output +section so you know when you have succeeded. + +```bash +git clone https://git.fromaitochitta.com/fromaitochitta/claude-code-claude-md.git +cd claude-code-claude-md +claude +``` + +Then open `exercises/01-write-your-first.md` and paste the prompt into Claude Code. + +## Domain + +**Claude Code Memory and Instructions** - This repo is part of the Claude Code Foundation series on +From AI to Chitta. See the full series for related concepts. + +## About + +Built by [Kjell Tore Guttormsen](https://fromaitochitta.com) as +part of the From AI to Chitta project, exploring the intersection +of AI tools and inner development. + +MIT License. diff --git a/exercises/01-write-your-first.md b/exercises/01-write-your-first.md new file mode 100644 index 0000000..13e84c6 --- /dev/null +++ b/exercises/01-write-your-first.md @@ -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). diff --git a/exercises/02-hierarchy-in-action.md b/exercises/02-hierarchy-in-action.md new file mode 100644 index 0000000..48ed6f2 --- /dev/null +++ b/exercises/02-hierarchy-in-action.md @@ -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). diff --git a/exercises/03-audit-and-improve.md b/exercises/03-audit-and-improve.md new file mode 100644 index 0000000..691a2bd --- /dev/null +++ b/exercises/03-audit-and-improve.md @@ -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