What you’ll make
A project-root CLAUDE.md with verified commands, a map of the relevant files, and a fresh-session test of one project rule.
Worked example
Point Claude at the source of a sound library’s guide pages
A shop has Markdown guides under guides-src/ and generated pages under public/guides/. Its package.json defines a build command that renders the pages and a check command that validates links. The project file names both directories, tells Claude where to change a guide summary, and records the commands exactly as the creator runs them from the root.
The creator starts a fresh session and asks where to update a guide summary. Claude finds the correct Markdown file but plans to run a generic test command. The creator adds a rule tying guide changes to the repository’s link check and repeats the test. The second run changes the source summary and reports the actual link-check result.
Before you start
- Open your repository in an editor and locate its README, dependency manifest, and test scripts. Check whether it already has project instructions, including a CLAUDE.md or an AGENTS.md.
- Choose a small test task that exercises a real project rule, such as updating a label stored in a shared copy file. Record the correct file and verification command before you try it with Claude Code.
Put the instructions where Claude can find them
Open the project folder and check for CLAUDE.md or AGENTS.md before you create anything. If there’s already a shared instructions file, read it first so you can carry forward the rules the project relies on. Adding a CLAUDE.md can affect whether Claude Code loads AGENTS.md under its default settings.
In my sound library’s website repo, I start in the same folder as README.md and package.json. I look for CLAUDE.md and AGENTS.md and open either one I find.
If there’s already a root CLAUDE.md, that’s the file I’ll update. If I only find AGENTS.md, I’ll check which instructions Claude loads before deciding where to add the site rules.
Map the files a new contributor needs
Start with one sentence about the product and its audience. Then find one file you edit and one file the build creates from it. Open both so you can name the real paths in the next step.
I write ‘This site sells sound effects and publishes guides on using them in videos.’ I open guides-src/adding-room-tone.md and find the corresponding page under public/guides/.
My map tells Claude where the work starts and where it ends. Edit the summary in guides-src/adding-room-tone.md. The build produces the published page in public/guides/.
Verify commands from their working directories
Copy the project’s own commands for building and checking a change. Run them from the documented folder before you include them. Write down the expected result and any setup you needed. If one fails, record the error so Claude can see what still needs checking.
The sound library’s package.json defines build and check:links. I try npm run build and then npm run check:links from the repo root.
In my notes, I record that the first command writes the guide pages and the second reports any broken links. Now I have both the commands and a way to tell whether they worked.
Write rules as decisions
Run the prompt here with the file map and commands you’ve checked. If you’re in chat, attach the README, package configuration, and any existing instructions. Read the draft next to the files it cites. Keep the rules you can verify, then save the draft to the shared instructions file.
I give Claude the sound library’s README, package.json, and the map from step 2. I explain that a summary change needs a rebuild and a link check.
The draft might say ‘When you update a guide summary, edit the matching file in guides-src/, run the build from the repo root, and run the link check.’ I check that the commands under that rule match the ones I just ran.
Draft a CLAUDE.md from this repo
Paste this in Claude Code from the repo root, or attach the listed files if you’re in a chat.
Help me write the shared CLAUDE.md for [repo]. The app is [what it does and who uses it]. Check [existing instruction files, README, package or task configuration, CI config, and a short directory listing]. If you can’t read the repo, tell me which files to attach. Write a draft I can paste in. Include what the app does, where to make its common changes, which files are generated, and the commands to run from the right directories. For each repo-specific rule, give a short trigger and what to do, such as “If you edit guide copy, update the source JSON and regenerate the pages.” Separate confirmed commands from anything I still need to test. After the draft, show a source path for each command and important rule. Flag conflicts with existing instructions, missing files, and anything that belongs in a task-specific skill. Leave the repo files untouched.
Check loading and behavior in a fresh session
Start a fresh Claude Code session in the repo. Run /context all and look for the expected path under Memory files. Try the review prompt with your draft, then ask where Claude would make one small change and how it would check the result. If the answer matches your notes, try the change on a test branch or in a scratch copy. Save the instructions and a short note of what worked.
I ask where to change the room tone guide summary and how to verify it. My expected answer is guides-src/adding-room-tone.md followed by the build and link check.
If Claude points to the published HTML, I make the source rule more direct and try again in a fresh session. I’m done when I can see the right source change in the diff and the link check passes.
Check the draft against the repo
Use this after you’ve drafted CLAUDE.md and checked that the instructions load.
Here’s my CLAUDE.md draft: [paste or path]. Review it against [repo docs and config]. Make a table with claim, evidence, and fix. Pay special attention to which folder commands run from, which files are generated, and what needs local setup. Report anything you haven’t verified as unverified. Then give me two short fresh-session requests I can try. For the first, ask where Claude would make [small representative change] and which check it would run. For the second, ask it to plan a change that touches generated output. Write the file paths and command I should expect in each answer. Don’t run commands or edit files during this review.
Check your result
- The fresh session lists the expected project instruction path under Memory files in /context all.
- The sample task uses the correct source file, working directory, and verification command.
- Each rule in the shared file describes an observable action or identifies a relevant reference.
Troubleshooting
What if Claude cannot find the project instructions?
Check the starting directory, the filename, and the loaded paths under Memory files in /context all. If the file lives in a subproject, start there to test its scope.
What if Claude gives the right explanation and then edits the wrong file?
State exactly which file is authoritative and when to regenerate derived output. Confirm there is no contradictory instruction, then retry and inspect the diff.