Module 01 · Claude Code Fundamentals
CLAUDE.md and Project Context: Teaching Claude Your Codebase
Open lesson + course map
On this lesson
Course outline
Module 1 · Claude Code Fundamentals
Module 2 · CLI Workflows
Module 3 · Model Context Protocol Basics
Module 4 · Building an MCP Server
CLAUDE.md provides persistent project instructions. Anthropic’s current documentation explicitly describes these instructions as context, not enforced configuration. Use them for stable facts and workflow; use settings, hooks, OS controls, and service authorization for hard boundaries.
// concept
Write Only Durable Context
Include:
- project purpose and architecture map;
- authoritative commands for test, lint, build, and formatting;
- file ownership and generated-file rules;
- coding conventions that are not discoverable;
- data/security constraints and prohibited areas;
- definition of done and escalation conditions.
Avoid secrets, long tutorials, temporary task notes, contradictory rules, and facts already obvious from the repository. Anthropic recommends concise, specific instructions; path-scoped rules or skills suit narrower procedures.
// concept
Make Rules Verifiable
Weak: Write good secure code.
Better:
- Validate API request bodies with schemas in src/schemas.
- Never log Authorization, cookies, OTPs, or payment payloads.
- Run npm test and npm run lint for src/** changes.
- Do not edit generated/**; run npm run generate after schema changes.
- Ask before database migrations or new dependencies.If a repository uses AGENTS.md, current Claude documentation explains that CLAUDE.md can import it. Review imports so an untrusted repository cannot silently load unrelated local files.
// worked_example
Worked Example
A Karachi SaaS team’s 400-line instruction file contains outdated commands and style essays. They replace it with an 80-line root file: architecture, exact gates, generated boundaries, secrets, and migration policy. Frontend-specific rules move into a path-scoped file.
The team tests three representative tasks and uses /context or current equivalent to verify loading. A command-deny requirement is placed in enforced settings rather than relying on prose.
// failure_cases
Failure Cases to Diagnose
6 cases to diagnose
Instructions contain API keys
remove and rotate exposed values.
Two nested files conflict
define ownership and remove drift.
Every task procedure loads globally
move it to a skill or scoped rule.
Hard prohibition exists only in Markdown
enforce it technically.
File grows after every session
schedule pruning and source review.
Imported path is outside trusted workspace
require explicit approval.
// pakistan_angle
Pakistan Angle
Document actual local commands, Windows/WSL differences, and PKT operational expectations if they affect development. Do not encode stereotypes such as assuming every Pakistani user prefers Roman Urdu; specify tested localization requirements.
Agency repositories should name client data boundaries and forbid copying production exports into prompts or fixtures. Keep client-specific rules in the client repository, not a personal global file that can leak context elsewhere.
// hands_on
Hands-On Exercise
5 steps
Draft a CLAUDE.md under 100 useful lines.
Convert vague instructions into testable rules.
Move one narrow procedure to scoped guidance.
Enforce one hard boundary outside the file.
Test loading and prune contradictions.
// completion_rubric
Completion Rubric
6 checks — tick as you verify
// sources
Sources
2 official sources — check every claim yourself
// check_yourself
Check yourself
4 questions · answers and options are taken word-for-word from this course
1 / 4 · diagnose
Your work shows this failure mode: “Instructions contain API keys.” What does the lesson tell you to do about it?