.claude Complete Setup Guide: From Setup to Mastering Claude Code — You Are Falling Behind If You Are Not Using It
The definitive guide to setting up and mastering the .claude folder for Claude Code. Learn how to configure CLAUDE.md, rules, skills, commands, hooks, and team-wide context files that turn Claude into a senior engineer on your team. Includes a downloadable complete team guide.
Every few years, a tool comes along that permanently changes how developers work. Git did it. Docker did it. VS Code did it. Right now, Claude Code is doing it — and the .claude folder is the key to unlocking its full power.
If you are still using Claude Code without a .claude folder, you are essentially driving a Formula 1 car in first gear. You are getting some value, sure, but you are leaving 90% of the performance on the table. This guide will take you from zero to a fully configured, team-ready .claude setup that turns Claude into a senior engineer who knows your codebase, follows your rules, and never forgets your architecture decisions.
I wrote this because I could not find a single comprehensive resource that covered everything in one place. This is the one-stop guide I wish existed when I started.
Download the Complete .claude Team GuideWhat Is the .claude Folder and Why Does It Matter?
The .claude folder is a special directory at the root of your project that Claude Code reads automatically every time it starts a session. Think of it as your project's "brain" that gives Claude everything it needs to be useful from the very first prompt.
Without a .claude folder, every Claude Code session starts from scratch. Claude has to guess your conventions, ask you about your architecture, and figure out your team's rules by trial and error. With a well-structured .claude folder, Claude starts every session already knowing:
- What your project does and how it is built
- Which libraries and frameworks you use
- Your coding standards and naming conventions
- Your security requirements and authentication patterns
- How to run tests, build Docker images, and deploy to production
- Your team's communication norms and decision-making process
This is not a nice-to-have. This is the difference between Claude being a random coding assistant and Claude being a productive team member.
The Complete Folder Structure
Before we dive into each file, here is the full structure we are building:
.claude/
├── CLAUDE.md # Root context file — Claude reads this first
├── settings.json # Claude Code permissions and hooks
│
├── rules/ # Enforceable behavioral rules
│ ├── general.md # Universal rules for all teams
│ ├── security.md # Auth, secrets, and Keycloak rules
│ ├── git.md # Commit, branch, PR rules
│ ├── testing.md # Testing standards
│ ├── api-contracts.md # API design rules
│ ├── docker-aws.md # Container and cloud deployment rules
│ ├── logging-observability.md # Logging and monitoring rules
│ └── accessibility.md # Accessibility and UX standards
│
├── skills/ # Reusable task templates
│ ├── create-feature.md # How to scaffold a new feature
│ ├── write-tests.md # How to write tests
│ ├── review-pr.md # PR review checklist
│ ├── keycloak-integration.md # Auth integration patterns
│ ├── docker-deploy.md # Build and deploy to AWS
│ ├── openapi-spec.md # API spec management
│ ├── debug-production.md # Production debugging runbook
│ └── migrate-database.md # Database migration patterns
│
├── commands/ # Slash command shortcuts
│ ├── feature.md # /feature — scaffold new feature
│ ├── test.md # /test — run or generate tests
│ ├── deploy.md # /deploy — deployment helper
│ ├── review.md # /review — PR review assistant
│ └── audit.md # /audit — security audit
│
├── context/ # Long-lived reference documents
│ ├── architecture.md # System architecture overview
│ ├── team-norms.md # Team agreements and culture
│ ├── tech-stack.md # Canonical technology choices
│ ├── environments.md # Dev/staging/prod guide
│ └── onboarding.md # New member quick-start
│
└── hooks/ # Automated safety checks
└── pre_write_check.py # Block writes to sensitive files
Each layer has a specific purpose. Let us go through them one by one.
Layer 1: CLAUDE.md — The Root Context File
CLAUDE.md is the single most important file in your entire .claude folder. Claude reads this file first, every single time. It is your project's elevator pitch, your ground rules, and your directory map all in one.
Here is what a production-quality CLAUDE.md looks like:
# CLAUDE.md — Project Context for AI Assistance
## What This Project Is
A production-grade Todo Application demonstrating the team's reference
architecture. It includes:
- Backend: Python FastAPI with PostgreSQL, deployed on AWS ECS (Fargate)
- Frontend: React web app + Flutter mobile (iOS and Android)
- Auth: Keycloak (OIDC/OAuth2) for all authentication and authorization
- Infrastructure: Docker, AWS ECS or Kubernetes (EKS), Terraform
- CI/CD: GitHub Actions
## How to Work in This Repo
### Before you write any code
1. Read .claude/context/architecture.md to understand the system.
2. Read .claude/context/tech-stack.md to confirm your chosen libraries.
3. Read the relevant .claude/rules/ files for your area of work.
### Non-negotiable team rules
- Never commit secrets. Use AWS Secrets Manager or environment variables.
- Every endpoint requires authentication via Keycloak JWT validation.
- Every new feature requires tests (unit + integration).
- OpenAPI spec must be updated when the API contract changes.
- All Docker images are pinned to specific digest SHAs in production.
### Claude's role in this project
Claude is a senior engineer on this team. It:
- Follows all rules in .claude/rules/ without being asked.
- Uses patterns from .claude/skills/ when scaffolding features.
- Reads .claude/context/ files before making architecture decisions.
- Never invents new patterns when existing ones exist in this repo.
- Asks clarifying questions before making breaking changes.
Why This Works
Notice the structure. It answers three questions immediately:
- What is this? — Claude knows the tech stack, the deployment target, and the architecture before writing a single line of code.
- How should I work here? — Claude knows to read context files before making decisions and to follow existing patterns.
- What am I NOT allowed to do? — The non-negotiable rules act as guardrails that prevent the most common mistakes.
The "Claude's role" section is especially powerful. By framing Claude as a "senior engineer on this team," you are setting expectations for the quality of output. Claude will produce code that matches the quality bar of a senior team member rather than a quick prototype.
Layer 2: settings.json — Permissions, Hooks, and Safety
The settings.json file controls what Claude is allowed to do and what happens automatically after it does something. This is where you build your safety net.
{
"permissions": {
"allow": [
"Bash(git diff:*)",
"Bash(git log:*)",
"Bash(pytest:*)",
"Bash(ruff check:*)",
"Bash(docker build:*)",
"Bash(npm test:*)",
"Bash(terraform plan:*)",
"Read(**)",
"Write(backend/**)",
"Write(frontend/**)"
],
"deny": [
"Bash(git push:*)",
"Bash(terraform apply:*)",
"Bash(terraform destroy:*)",
"Bash(rm -rf:*)",
"Write(.env)",
"Write(.env.production)",
"Write(**/*.pem)",
"Write(**/*.key)"
]
},
"hooks": {
"PostToolUse": [
{
"matcher": "Write(backend/**/*.py)",
"hooks": [
{
"type": "command",
"command": "ruff check --fix \"$CLAUDE_FILE_PATH\" && ruff format \"$CLAUDE_FILE_PATH\""
}
]
}
]
}
}
Understanding the Permission Model
The allow list is explicit about what Claude can do without asking. Reading files, running tests, building Docker images, running linters — these are all safe operations that Claude should never need to ask permission for.
The deny list is the real safety net. Claude can never push to git, apply Terraform changes, delete files recursively, or write to sensitive files like .env or private keys. Even if you ask Claude to do these things, it physically cannot. This is not about trust — it is about building systems that prevent mistakes.
The Power of Hooks
Hooks are the secret weapon most developers miss. A PostToolUse hook runs automatically after Claude writes a file. In the example above, every time Claude writes a Python file in the backend, ruff automatically lints and formats it. This means:
- Claude's code is always formatted correctly
- Linting errors are caught and fixed immediately
- You never have to ask "did you run the linter?"
You can add hooks for any language:
{
"matcher": "Write(frontend/web/**/*.ts)",
"hooks": [
{
"type": "command",
"command": "npx eslint --fix \"$CLAUDE_FILE_PATH\""
}
]
}
PreToolUse Hooks for Security
PreToolUse hooks run before Claude writes a file, giving you a chance to block the write entirely:
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "python .claude/hooks/pre_write_check.py \"$CLAUDE_FILE_PATH\""
}
]
}
The pre_write_check.py script checks if the file path matches any sensitive patterns (like .env, .pem, secrets/) and blocks the write if it does. This adds a second layer of protection on top of the deny list.
Layer 3: Rules — Encoding Your Team's Standards
Rules are markdown files in .claude/rules/ that tell Claude exactly how your team works. Unlike CLAUDE.md (which is a high-level overview), rules are detailed, specific, and enforceable.
Why Separate Rule Files?
You could put everything in CLAUDE.md, but that creates a massive file that is hard to maintain. Separate rule files let you:
- Update one area without touching everything else
- Share specific rules with new team members
- Let Claude load only the relevant rules for the task at hand
General Coding Rules
The general.md file covers standards that apply to every team member and every language:
# General Coding Rules — All Teams
## Language and Style
- Python: 3.12+, type hints required, ruff for lint/format
- TypeScript: strict mode, no any types without justification
- Every public function must have a docstring
- Max line length: 100 characters
- No dead code. No commented-out code blocks.
## File Organization
- One class per file for domain models and services
- Keep files under 300 lines
- Circular imports are forbidden
## Error Handling
- Never swallow exceptions silently
- FastAPI: Use HTTPException with explicit status codes
- All error paths must be tested
## Dependencies
- No new dependencies without tech-lead review
- Pin all dependencies to exact versions
- Run audit tools in CI. Zero critical CVEs.
Security Rules
Security rules are critical because they prevent the most dangerous mistakes:
# Security Rules
## Secrets Management
- NEVER hardcode secrets, API keys, tokens, or passwords
- All secrets stored in AWS Secrets Manager
- Secret scanning (gitleaks) runs in CI
## Authentication
- Every protected endpoint MUST validate the Bearer JWT
- JWT validation requires: signature, audience, issuer, expiry
- Access tokens must not be stored in localStorage (web)
## Input Validation
- All API inputs validated with Pydantic (backend) or Zod (frontend)
- Never pass raw user input to database queries
- CORS: no wildcard origins in production
Testing Standards
Testing rules ensure Claude always writes tests with new features:
# Testing Standards
## Required Coverage
- Backend: 80% line coverage minimum, 100% for auth paths
- Frontend Web: 70% minimum
- Mobile: 70% minimum
## Minimum Tests Per Feature
- Unit tests for service/business logic
- Integration tests for API routes
- Auth tests: valid token, expired token, wrong audience, missing token
Other Rule Files
The downloadable guide includes complete rule files for:
git.md— Branch naming, commit message format, PR requirementsapi-contracts.md— REST design, versioning, OpenAPI spec managementdocker-aws.md— Dockerfile best practices, ECS/K8s deployment ruleslogging-observability.md— Structured logging, tracing, metricsaccessibility.md— WCAG compliance, i18n, touch target sizes
Layer 4: Skills — Teaching Claude Complex Tasks
Skills are step-by-step playbooks for complex, multi-step tasks. While rules tell Claude what to do, skills tell Claude how to do it.
The Create Feature Skill
This is probably the most valuable skill you can write. It tells Claude exactly how to scaffold a new feature across every layer of your stack:
# Skill: Create a New Feature End-to-End
## Step 1: Design the API Contract First
Update docs/api/openapi.yaml with the new endpoints before writing code.
## Step 2: Backend Implementation
1. Database model (SQLAlchemy with UUID, timestamps)
2. Repository layer (async, scoped to user)
3. Service layer (business logic, domain exceptions)
4. Route layer (FastAPI, dependency injection, auth)
5. Database migration (Alembic, reversible)
## Step 3: Write Tests
- Unit tests for service methods
- Integration tests for routes
- Auth tests: 401 and 403 scenarios
## Step 4: Frontend
- API client method
- React Query hooks
- UI components
- Route registration
## Step 5: Documentation
- Update OpenAPI spec
- Update env-vars.md if needed
- Write ADR if a significant decision was made
Why Skills Matter So Much
Without a create-feature skill, here is what happens when you ask Claude to "add due dates to todos":
- Claude writes the model
- You realize it forgot the migration
- Claude writes the migration
- You realize it forgot the repository
- Claude writes the repository
- You realize the tests are missing
- Back and forth continues
With the skill, Claude follows a consistent checklist every time. It never forgets a step because the step-by-step process is encoded in the skill file.
The Keycloak Integration Skill
Authentication is notoriously tricky to get right, and it varies by platform. The Keycloak integration skill provides copy-paste patterns for every platform your team uses:
Backend (FastAPI):
async def get_current_user(
credentials: HTTPAuthorizationCredentials = Depends(BEARER),
) -> TokenData:
token = credentials.credentials
payload = jwt.decode(
token,
get_jwks(),
algorithms=["RS256"],
audience=settings.KEYCLOAK_CLIENT_ID,
issuer=f"{settings.KEYCLOAK_URL}/realms/{settings.KEYCLOAK_REALM}",
)
return TokenData(
user_id=payload["sub"],
roles=payload.get("realm_access", {}).get("roles", []),
)
Web (React):
export const keycloak = new Keycloak({
url: import.meta.env.VITE_KEYCLOAK_URL,
realm: import.meta.env.VITE_KEYCLOAK_REALM,
clientId: import.meta.env.VITE_KEYCLOAK_CLIENT_ID,
});
Flutter (Mobile):
Future<TokenResponse?> signIn() async {
return appAuth.authorizeAndExchangeCode(
AuthorizationTokenRequest(
Env.keycloakClientId,
'${Env.appScheme}://callback',
scopes: ['openid', 'profile', 'email'],
),
);
}
When any team member asks Claude to add authentication, it uses the exact same patterns regardless of platform. This eliminates the "we do auth differently on iOS vs Android vs Web" problem entirely.
Other Essential Skills
The downloadable guide includes complete skills for:
write-tests.md— Test fixtures, integration test patterns, mocking strategiesdocker-deploy.md— Building images, scanning, pushing to ECR, deployingopenapi-spec.md— Generating and validating OpenAPI specificationsdebug-production.md— Step-by-step production debugging runbookmigrate-database.md— Safe migration patterns including expand-contract
Layer 5: Commands — Slash Command Shortcuts
Commands are quick-access shortcuts that trigger specific workflows. They live in .claude/commands/ and are accessed with a slash:
/feature — Scaffold a New Feature
# /feature — Scaffold a New Feature
Usage: /feature add-due-dates --platform backend
What I will do:
1. Ask clarifying questions about the feature
2. Execute the create-feature skill step by step
3. Create all required files
4. Update the OpenAPI spec
5. Print a summary of created files
/review — PR Review Assistant
# /review — PR Review Assistant
What I will do:
1. Run git diff main...HEAD to see all changes
2. Check against every rule in .claude/rules/
3. Look for: hardcoded secrets, missing auth, missing tests
4. Output a structured review report
/deploy — Deployment Helper
# /deploy — Deployment Helper
Usage: /deploy backend staging
What I will do:
1. Validate the environment
2. Walk through the deployment checklist
3. Show the exact commands needed
4. Never autonomously apply production changes
/audit — Security Audit
# /audit — Security Audit
Usage: /audit --scope auth
What I will do:
1. Scan for violations of security rules
2. Check for hardcoded secrets, missing auth, CORS issues
3. Run dependency vulnerability checks
4. Generate a dated audit report
Layer 6: Context — Long-Lived Reference Documents
Context files are living documents that Claude reads when making decisions. They answer the questions that come up repeatedly: "What is our tech stack?", "How does the architecture work?", "What are the environment URLs?"
Architecture Overview
# System Architecture
Browser/App → AWS ALB (HTTPS/TLS) → ECS Fargate (FastAPI) → Aurora PostgreSQL
↗ Keycloak (OIDC/SSO)
↗ S3 + CDN (Web/Assets)
↗ AWS Secrets Manager
## Authentication Flow
1. User opens the app
2. App redirects to Keycloak (PKCE)
3. User authenticates
4. Keycloak issues tokens
5. App attaches Bearer token to every API call
6. Backend validates JWT on every request
Tech Stack
The tech stack file is a lookup table that prevents Claude from suggesting libraries you have not approved:
| Concern | Choice | Version |
|---|---|---|
| Language | Python | 3.12 |
| Framework | FastAPI | 0.115+ |
| ORM | SQLAlchemy (async) | 2.0+ |
| Validation | Pydantic v2 | 2.x |
| Testing | pytest + pytest-asyncio | latest |
| Linting | Ruff | latest |
When Claude needs to add a new dependency, it checks this table first. If the dependency is not listed, Claude knows to flag it for tech-lead review instead of just adding it.
Environments Guide
| Environment | Purpose | URL | Deployment |
|---|---|---|---|
| Local | Developer machine | localhost:8000 | docker compose |
| Dev | Shared integration | api.dev.todo.internal | Auto (push to dev) |
| Staging | Pre-prod validation | api.staging.todo.internal | Auto (merge to main) |
| Production | Live customers | api.todo.company.com | Manual gate |
Team Norms
This is the file most teams skip and it is the one that makes the biggest difference. Team norms encode your culture:
## Working Agreements
- Psychological safety: It is safe to say "I don't know."
- Definition of Done: merged to main with tests passing
- Tech debt: 20% of capacity reserved every sprint
- Documentation: if you figured it out, document it before closing the ticket
When Claude understands your team's culture, it writes PRs and documentation that match your team's voice. It knows to write ADRs for significant decisions, to link Jira tickets, and to flag breaking changes for discussion.
Onboarding
The onboarding file is a quick-start for new team members. It doubles as a self-test: if Claude (or a new engineer) can follow this guide and get a working environment in under a day, your onboarding is solid.
Layer 7: Hooks — Automated Safety Checks
Hooks are scripts that run automatically before or after Claude takes an action. The most important hook is the pre-write check:
#!/usr/bin/env python3
"""Pre-write hook: blocks writes to sensitive file paths."""
import sys
import re
BLOCKED_PATTERNS = [
r"\.env$",
r"\.env\.production$",
r".*\.pem$",
r".*\.key$",
r".*/secrets/.*",
r".*credentials.*",
r"alembic/versions/.*",
]
def main():
if len(sys.argv) < 2:
sys.exit(0)
filepath = sys.argv[1]
for pattern in BLOCKED_PATTERNS:
if re.search(pattern, filepath, re.IGNORECASE):
print(f"BLOCKED: Writing to '{filepath}' is not allowed.")
sys.exit(1)
sys.exit(0)
if __name__ == "__main__":
main()
Notice alembic/versions/.* in the blocked patterns. Database migrations are intentional operations — you do not want Claude auto-generating migrations without explicit human review.
Putting It All Together: The Complete Setup Script
Here is a one-command script to create the entire folder skeleton:
# Run from your repo root
mkdir -p .claude/{rules,skills,commands,context,hooks}
# Core files
touch .claude/CLAUDE.md
touch .claude/settings.json
# Rules
touch .claude/rules/general.md
touch .claude/rules/security.md
touch .claude/rules/git.md
touch .claude/rules/testing.md
touch .claude/rules/api-contracts.md
touch .claude/rules/docker-aws.md
touch .claude/rules/logging-observability.md
touch .claude/rules/accessibility.md
# Skills
touch .claude/skills/create-feature.md
touch .claude/skills/write-tests.md
touch .claude/skills/review-pr.md
touch .claude/skills/keycloak-integration.md
touch .claude/skills/docker-deploy.md
touch .claude/skills/openapi-spec.md
touch .claude/skills/debug-production.md
touch .claude/skills/migrate-database.md
# Commands
touch .claude/commands/feature.md
touch .claude/commands/test.md
touch .claude/commands/deploy.md
touch .claude/commands/review.md
touch .claude/commands/audit.md
# Context
touch .claude/context/architecture.md
touch .claude/context/team-norms.md
touch .claude/context/tech-stack.md
touch .claude/context/environments.md
touch .claude/context/onboarding.md
# Hooks
touch .claude/hooks/pre_write_check.py
chmod +x .claude/hooks/pre_write_check.py
echo "Done. Now fill in each file with your team's content."
How the Layers Work Together
Here is a real-world example of how all the layers interact when you ask Claude to "add a priority field to todos":
graph TD
A[You: Add priority field] --> B[Claude reads CLAUDE.md]
B --> C[Claude reads architecture.md]
C --> D[Claude reads tech-stack.md]
D --> E[Claude loads create-feature skill]
E --> F[Step 1: Update OpenAPI spec]
F --> G[Step 2: Add SQLAlchemy model field]
G --> H[Step 3: Generate Alembic migration]
H --> I[Step 4: Update service layer]
I --> J[Step 5: Update router]
J --> K[Step 6: Write tests]
K --> L[PostToolUse hook: ruff format]
L --> M[Step 7: Update frontend]
M --> N[Complete: summary of changes]
- Claude reads
CLAUDE.mdand understands the project - Claude reads
architecture.mdto see where the todo model lives - Claude reads
tech-stack.mdto confirm SQLAlchemy 2.0, Pydantic v2, etc. - Claude loads the
create-featureskill and follows it step by step - At each step, Claude checks the relevant rules (general, testing, api-contracts)
- After every Python file write, the PostToolUse hook runs ruff automatically
- The pre-write hook prevents any accidental writes to sensitive files
The result is production-quality code, with tests, documentation, and proper formatting — all from a single prompt.
Key Principles That Make This Work
| Principle | What It Means |
|---|---|
| Context first | CLAUDE.md and context files prevent Claude from reinventing the wheel |
| Security by default | Deny lists, hooks, and security rules make it physically impossible to leak secrets |
| Platform agnostic | Skills cover iOS, Android, Flutter, Web, and Backend with the same patterns |
| Guardrails, not gatekeepers | Claude can read everything and write most things — but cannot push, deploy, or touch production |
| Automated quality | Post-write hooks run linters and formatters automatically |
| Living documentation | Architecture docs, tech stack tables, and onboarding guides all stay in sync |
| Team culture encoded | Claude understands your decision-making process, not just your code |
Common Mistakes to Avoid
Putting everything in CLAUDE.md. Split your content into rules, skills, and context. A 2000-line CLAUDE.md is hard to maintain and hard for Claude to parse effectively.
Forgetting to deny destructive commands. Always deny git push, terraform apply, rm -rf, and anything that touches production. Even if you trust Claude, mistakes happen.
Skipping the tech stack file. Without it, Claude will suggest whatever library it thinks is best. With it, Claude uses your approved stack every time.
Not writing the team-norms file. This is what turns Claude from a code generator into a team member. It needs to understand your PR process, your communication norms, and your definition of done.
Making skills too vague. A skill that says "write tests" is useless. A skill that says "write unit tests for the service layer using pytest-mock, integration tests using httpx AsyncClient, and auth tests covering 401/403" is actionable.
Getting Started Today
You do not have to implement everything at once. Start with these three files and add more over time:
CLAUDE.md— What is your project? What are the non-negotiable rules? How should Claude work here?settings.json— What is Claude allowed and denied? Add at least one post-write hook for auto-formatting.rules/general.md— Your coding standards for all languages.
Once those three files are in place, you will immediately notice a difference in Claude's output quality. From there, add skills, commands, and context files as your team needs grow.
The developers who set this up now will have a significant productivity advantage in six months. The ones who wait will spend that time doing manually what Claude could have been doing automatically.
Download the complete guide below and start building your .claude folder today.