Your Project CLAUDE.md
This is a member-only chapter. Log in with your Signal Over Noise membership email to continue.
Log in to readModule 6 · Section 2 of 7
Your Project CLAUDE.md
A project CLAUDE.md lives at .claude/CLAUDE.md in your project root. Claude Code reads it at session start. Without it, every session starts from scratch. With it, Claude Code knows your project’s conventions, file structure, and constraints from the first message.
Here’s what a Astro site CLAUDE.md needs:
# My Site — Claude Code Instructions
## Project
This is an Astro 5 site. Framework: Astro. Language: TypeScript.
Package manager: npm. Build output: dist/.
## Structure
- Pages: src/pages/
- Layouts: src/layouts/ (BaseLayout.astro is the base)
- Components: src/components/
- Content: src/content/ (typed collections, config in src/content/config.ts)
- Styles: src/styles/global.css (CSS custom properties — no hardcoded values)
- Public assets: public/
## Commands
- Dev server: npm run dev (localhost:4321)
- Build: npm run build
- Preview build: npm run preview
- Deploy: ./deploy.sh
## Rules
- Read a file before editing it
- Use CSS custom properties from src/styles/global.css — never hardcode hex values
- Follow the existing component structure before creating new ones
- Run npm run build to verify before telling me something is done
- All content in British English
- Conventional commits for git messages
## Conventions
- Components receive typed props via Astro.props
- Pages import layouts and wrap content in them
- Collection frontmatter must match the schema in src/content/config.ts
- Images go in public/images/ and are referenced from /images/This file is the difference between “Claude Code helping with one task” and “Claude Code building your entire site without context gaps”. Invest 20 minutes writing a thorough one at the start of every project.