Write a CLAUDE.md that actually helps

Lesson objective

By the end of this lesson, you will be able to write a short, useful CLAUDE.md for your repository, choose where each instruction belongs (user, project, local, subdirectory, path-scoped rule, import) and evolve it based on the agent's mistakes.

Where it fits

Master context and CLAUDE.md

What does the agent know about my project at any moment, and how do I give it the right information without drowning it?

Lessons in this module

1. What Claude Code has in mind, and how to manage it
2. Write a CLAUDE.md that actually helps (this lesson)

What you will learn in the course

This lesson is part of the course Work with Claude Code on a real project: context, planning, review

• Explain what fills Claude Code's context window and manage it (/context, /clear, /compact, resuming and naming sessions), taking cost into account.
• Write a short, useful CLAUDE.md placed at the right level of the hierarchy (user, project, local, subdirectory, path-scoped rules), with imports if needed.
• Run a task on existing code as explore, plan, code, commit, with plan mode, verification criteria and Git rather than checkpoints alone.
• Choose and justify the right mechanism for a need (CLAUDE.md, skill or command, subagent, MCP server, hook) and set it up in the repository.
• Choose a permission mode and write allow, ask and deny rules suited to the project's risks, in the right settings file.
• Write simple hooks as deterministic guardrails (block, format, verify) and know their risks and limits.
• Review the agent's work with a checklist (scope, tests, secrets, migrations, dependencies) and an independent review, and know when to automate it in non-interactive mode or in GitHub Actions.

Related courses

• Build and ship a web app with an AI coding agentJunior · ~2 hr 45 min
• Add a database, authentication and payments to your appAdvanced · ~4 hr
• Git for PMs: ship as a team without putting production at riskAdvanced · ~3 hr 30 min