A "Claude readiness" overlay for existing repositories. Add these files to any project — in any language — to give Claude Code the context it needs to be a useful, disciplined collaborator from day one.
Claude Code works best when it understands your project's purpose, conventions, and constraints. Without that context it makes reasonable guesses, but guesses drift. These files give Claude a stable, explicit foundation so it asks fewer clarifying questions and makes fewer wrong assumptions.
The overlay is a small set of Markdown files and a settings.json that you
copy into your repository, fill in, and commit. They are read automatically by
Claude Code at the start of every session.
Requires git and bash.
git clone https://github.com/MazamaScience/claude-overlay.git
cd claude-overlay
bash install.sh /path/to/your-repo
The script copies all overlay files into your repository, preserving their
relative paths. Any existing files that would be overwritten are renamed
in-place with a ~_OLD suffix before copying (e.g. CLAUDE.md~_OLD). If a
~_OLD backup already exists, a timestamp is appended instead.
Open a Claude Code session in your repository and paste the following prompt.
Claude will read the standardized overlay files, gather context from any ~_OLD
backups left by the installer, and fill in the project-specific TODO sections.
For this session, we will be adding a "claude overlay" to the current
repository. This means we will be standardizing our usage of the following
files:
* CLAUDE.md
* .claude/CLAUDE_ARCHITECTURE.md
* .claude/CLAUDE_STYLE_GUIDE.md
* .claude/settings.json
* files in .claude/commands/
Earlier versions of some of these files may be found with ~_OLD as part of
the file name.
Please review the standardized files first:
* CLAUDE.md
* .claude/CLAUDE_ARCHITECTURE.md
* .claude/CLAUDE_STYLE_GUIDE.md
* .claude/settings.json
Then gather information from the ~_OLD files and rewrite the standardized
project-specific files, filling in TODO sections wherever possible.
Do not modify .claude/CLAUDE_STYLE_GUIDE.md
You may need to review other files in the repository to properly complete
this task.
When you are done, I will review and make suggestions.
When Claude finishes, review its work, make corrections, and commit the overlay files:
git add CLAUDE.md .claude/
git commit -m "Add Claude Code overlay files"
After installation, your repository will contain:
your-repo/
├── CLAUDE.md ← project guide (you fill this in)
├── .claude/
│ ├── CLAUDE_ARCHITECTURE.md ← architecture notes (you fill this in)
│ ├── CLAUDE_STYLE_GUIDE.md ← working principles (ready to use)
│ ├── settings.json ← permissions (add your tool allows)
│ ├── commands/
│ │ ├── initial-project-review.md ← slash command: /initial-project-review
│ │ ├── code-review.md ← slash command: /code-review
│ │ ├── documentation-review.md ← slash command: /documentation-review
│ │ ├── wrap-up.md ← slash command: /wrap-up
│ │ └── pre-publish.md ← slash command: /pre-publish
│ └── skills/
│ └── generating-readme/
│ ├── SKILL.md ← skill: generating-readme
│ └── TEMPLATE.md ← standardized README template (ready to use)
CLAUDE.md lives at the repository root where Claude Code picks it up
automatically. Everything else lives under .claude/.
After installation, these commands are available in any Claude Code session:
| Command | Purpose | Ready after install? |
|---|---|---|
/initial-project-review |
Full onboarding review — design, risks, improvement suggestions | Yes — generic, no customization needed |
/code-review |
Comprehensive code review before a version bump | No — has TODO sections; fill in during "First Session" |
/documentation-review |
Review all documentation layers for completeness and consistency, including README drift against the generating-readme skill template |
No — has TODO sections; fill in during "First Session" |
/wrap-up |
End-of-session checklist — tests, build, docs, git status | No — has TODO sections; fill in during "First Session" |
/pre-publish |
Bump version, update changelog, run tests, tag, and hand off | No — has TODO sections; fill in during "First Session" |
/quiz |
Quick test of user's mental model of how the code works | Yes — generic, no customization needed |
The four commands marked "No" still work if run before customization, but their TODO placeholders mean Claude will ask you to fill in project-specific details (scope, version file, test command, etc.) on the fly rather than following a pre-tailored checklist. Running the "First Session" bootstrap prompt first avoids this.
Run any command by typing it in the Claude Code chat. Claude reads the command file and follows its instructions.
CLAUDE.md — The primary project guide. Claude reads this at the start of
every session. It tells Claude what the project is, what conventions to follow,
what constraints to respect, and what the review priorities are.
.claude/CLAUDE_ARCHITECTURE.md — Architecture notes. Describes module
layout, call graphs, key design decisions, and public API contracts. Helps Claude
avoid breaking changes and understand why things are structured the way they are.
.claude/CLAUDE_STYLE_GUIDE.md — Portable working principles. Covers
philosophy, refactoring approach, error handling, communication style, and review
priorities. Shared across projects; no project-specific content.
.claude/settings.json — Permissions. Controls which shell commands Claude
may run without prompting for approval, and which are always denied (secrets,
destructive operations). Add allow entries for your language toolchain — for
example:
- JavaScript/Node:
"Bash(npm run *)","Bash(node *)" - Python:
"Bash(python *)","Bash(pytest *)","Bash(pip *)" - R:
"Bash(Rscript *)","Bash(R -e *)"
.claude/commands/ — Slash commands. Structured prompts that guide Claude
through specific multi-step tasks. Run them with /command-name in the Claude
Code chat.
.claude/skills/generating-readme/ — A skill Claude uses when creating or
updating this project's top-level README.md. TEMPLATE.md is a generic,
ready-to-use README structure (component overview, tech stack, getting
started, development workflow, testing, deployment); SKILL.md tells Claude
how to fill it in from what's actually in this repo, and never to leave
placeholder text behind. One section — Development → Ending a Work Session —
is fixed, mandatory content documenting the /documentation-review →
/wrap-up → /pre-publish workflow; it's reproduced as-is rather than
filled in from the repo. The /documentation-review command checks
README.md against this template for drift. If you maintain a family of
sibling repos that should share one README shape, this is the file to keep
in sync across them.
The following videos are a helpful introduction to Claude features for software developers (Updated June 17, 2026):
- Beginner to advanced: https://www.youtube.com/watch?v=ujHXnlSVheI
- Claude code concepts: https://www.youtube.com/watch?v=ZlDnsf_DOzg
- Six Claude skills: https://www.youtube.com/watch?v=eRS3CmvrOvA
- How to find/build skills: https://www.youtube.com/watch?v=cxQLKsktiBA
- 👉Claude superpowers: https://www.youtube.com/watch?v=4XqVR6xI6Kw&t=447s
These files are not magic. They work because Claude Code reads them and uses
them as context. The more accurate and complete they are, the better Claude
performs. Keep them up to date as the project evolves — treat them the way you
treat a README.md: a first-class artifact of the project, not an afterthought.
When in doubt, let Claude help you write them. Run /initial-project-review on
a fresh repo and ask Claude to draft the CLAUDE.md sections based on what it
finds.