A "Claude readiness" overlay for existing repositories. Drop these files into 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.
After setup, 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
CLAUDE.md lives at the repository root where Claude Code picks it up
automatically. Everything else lives under .claude/.
cp claude-overlay/CLAUDE.md your-repo/CLAUDE.md
cp claude-overlay/.claude/CLAUDE_ARCHITECTURE.md your-repo/.claude/CLAUDE_ARCHITECTURE.md
cp claude-overlay/.claude/CLAUDE_STYLE_GUIDE.md your-repo/.claude/CLAUDE_STYLE_GUIDE.md
cp claude-overlay/.claude/settings.json your-repo/.claude/settings.json
cp -r claude-overlay/.claude/commands/ your-repo/.claude/commands/
Or clone this repo and run the copy commands above, or just copy files manually.
Open CLAUDE.md and replace every <!-- TODO --> block with information about
your project:
- Project Overview — what it does, who uses it, what its goals are
- Language and Style — language version, idioms, doc comment format
- Project-Specific Constraints — data conventions, API stability rules, anything Claude must not change without explicit approval
- Build, Test, Document — the exact commands to run
This file has two sections: one for human maintainers, one for AI assistants. Fill in the architecture, module map, and key design decisions. Claude will reference this file when making changes that touch multiple modules.
The settings.json already denies dangerous operations (secrets files,
destructive rm commands, sudo). Add allow entries for the tools your
project uses — for example:
- JavaScript/Node:
"Bash(npm run *)","Bash(node *)" - Python:
"Bash(python *)","Bash(pytest *)","Bash(pip *)" - R:
"Bash(Rscript *)","Bash(R -e *)"
Start a Claude Code session in your repository and run:
/initial-project-review
Claude will read the codebase, compare it to what you wrote in CLAUDE.md and
CLAUDE_ARCHITECTURE.md, flag gaps, and suggest improvements. This is also a
good way to let Claude help you write the TODO sections if you prefer to
start with an empty template.
git add CLAUDE.md .claude/
git commit -m "Add Claude Code overlay files"
After setup, these commands are available in any Claude Code session:
| Command | Purpose |
|---|---|
/initial-project-review |
Full onboarding review — design, risks, improvement suggestions |
/code-review |
Comprehensive code review before a version bump |
/documentation-review |
Review all documentation layers for completeness and consistency |
/wrap-up |
End-of-session checklist — tests, build, docs, git status |
/pre-publish |
Bump version, update changelog, run tests, tag, and hand off |
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).
.claude/commands/ — Slash commands. Structured prompts that guide Claude
through specific multi-step tasks. Run them with /command-name in the Claude
Code chat.
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.