claude-code-claude-md/exercises/03-audit-and-improve.md

# 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