The Builder's Guide to Claude Code

The Mindset

This isn't a chatbot. It's an operating layer.

Before the templates, the philosophy. Because the templates only work if you understand why they exist.

"Most people use Claude the way they use a search engine. A few treat it the way a conductor treats an orchestra."

Claude Code isn't just an AI assistant you type questions into. When configured intentionally, it becomes a structured operating layer — a partner that remembers your conventions, delegates work to specialists, learns from what didn't work, and executes complex multi-step tasks while you focus on what requires your judgment.

The difference between "this AI is kind of helpful sometimes" and "this AI is genuinely accelerating my work every day" almost always comes down to structure. A few files, written thoughtfully, transform the experience entirely.

This guide shows you how to build that structure. The patterns here are drawn from real working implementations. Adapt freely — the best setup is the one you'll actually maintain.

The Four Building Blocks

📋

CLAUDE.md

The Mission Brief — loaded every session

Lives at: CLAUDE.md (repo root) or .claude/CLAUDE.md

⚡

Skills

Repeatable actions — triggered by /command

Lives at: .claude/skills/{name}.md

🤖

Agents

Specialist teammates — focused, scopeable

Lives at: .claude/agents/{name}.md

🧠

Memory

Persistent learning — survives sessions

Lives at: memory/ + memory/MEMORY.md

Building Block 1

CLAUDE.md — The Mission Brief

This file is loaded into every session automatically. It's your standing brief — mission, constraints, style preferences, and quick reference. Write it like you're briefing a brilliant new teammate on day one.

What goes in it?

1Mission — what this project is building and what success looks like. Be specific. A good mission brief tells Claude what matters most when tradeoffs arise.
2Hard Constraints — what Claude must never do without asking. Think: what would be catastrophic if done wrong? Secrets, production deploys, deletions, emails.
3Quick Reference — your verification commands, skill list, and which actions need your approval vs. which Claude can do autonomously.
4Style — output format preferences, comment conventions, tone. These prevent Claude from defaulting to its own habits over yours.
5Project Context — key architectural decisions, important file paths, domain knowledge that would take a new engineer a week to discover. Put it here so Claude has it on day one.

CLAUDE.md — Complete Template

# CLAUDE.md

## Mission
[What this project is building and what success looks like.
Be specific: a good mission brief tells Claude what "done" means
for any session, and what matters most when tradeoffs arise.

Example: "Build a customer data pipeline that pulls from
Salesforce, transforms to our schema, and writes to Postgres.
Success means clean data with audit trails — never silent failures."]

## Hard Constraints
1. Never expose secrets, API keys, or credentials in any output
2. Never push to production, send emails, or modify shared
   infrastructure without explicit human approval
3. Never delete files or data without confirmation
4. Never merge protected branches autonomously
5. [Add your own — what would be catastrophic if done wrong?]

## Quick Reference
Verify: [your main test command, e.g. npm test or pytest tests/]
Skills: [list your skills, e.g. .claude/skills/ — daily-review, deploy-check]
Ask before: IAM changes, deployments, emails, destructive operations
Proceed freely: Documentation, tests, new files, analysis, draft output

## Style
- Output format: [e.g. "dark-themed HTML for reports", "Markdown for docs"]
- Comments: [e.g. "only when the WHY is non-obvious, never narrate the WHAT"]
- Tone: [e.g. "direct and concise; no trailing summaries; no em dashes"]
- Response length: [e.g. "match the task; one-liners for trivial questions"]

## Project Architecture
[Key decisions and context Claude needs to understand your codebase.
What would a new engineer need to know on day one?

Example:
- Auth uses JWT, refresh tokens stored in Redis (not cookies)
- All DB queries go through /lib/db — never raw SQL in route handlers
- Feature flags via LaunchDarkly — check FEATURE_FLAGS.md before adding
- Staging deploys auto on merge to `develop`; prod requires tag]

## Agents
[List your specialist agents here once you build them.
Example:
- code-reviewer: reviews PRs for security, style, test coverage
- doc-writer: drafts technical docs and READMEs
- data-validator: validates schemas and checks data quality]

## Skills
[List your skills and their trigger phrases.
Example: `.claude/skills/` — /daily-review, /deploy-check, /schema-diff]

What makes a great CLAUDE.md?

Write the constraints first — they're the most important and easiest to forget when you're excited to write the fun stuff
The quick reference section is what you'll update most often — keep it maintainable
Project architecture notes age out fast; link to files rather than duplicating content
Read it aloud before saving — if it sounds like policy documentation, rewrite it as a briefing
Start minimal. Add sections when you notice Claude defaulting to the wrong behavior without them

Building Block 2

Skills — Repeatable Actions

Skills are slash commands that trigger predefined workflows. When you find yourself giving Claude the same multi-step instructions repeatedly, that's a skill waiting to be written.

When to create a skill

1You've typed the same instruction 3+ times in different sessions
2The task has a consistent sequence of steps (read X, do Y, write to Z, report W)
3The task has clear acceptance criteria — you know when it's done
4You want Claude to run it the same way every time, not improvise

Ideas for your first five skills

/daily-review — reads recent commits, open PRs, and any failing tests; produces a morning briefing
/deploy-check — validates config files, runs smoke tests, confirms env vars before a deploy
/doc-update — detects stale documentation by comparing README against recent code changes
/schema-diff — compares current DB schema against the expected schema and reports drift
/session-summary — summarizes what changed in the current session for handoff notes

.claude/skills/my-skill-name.md — Template

# Skill: my-skill-name

## Description
[One sentence: what this skill does when invoked.
Example: "Reads open PRs and recent commits, then produces a
concise morning briefing with any action items flagged."]

## When to invoke
- User types /my-skill-name
- User says "[natural language trigger phrase]"

## Steps
1. Read [any context files needed — be specific about paths]
2. [The core work — describe it precisely]
3. Write output to: local/output/{slug}-{date}.md
   (or wherever your output should go)
4. Report back: [tell the user the output path and one-line summary]

## Acceptance criteria
- [ ] Output file exists at the declared path
- [ ] [What content should it contain — be verifiable]
- [ ] No errors or silent failures
- [ ] [Any verification command the user can run]

## On failure
Report what failed, at which step, and what the user should do next.
Do not stop silently. A failed skill should always produce a clear
error message and a recovery suggestion.]

## Notes
[Any edge cases, prerequisites, or "watch out for" context
that would surprise someone running this skill for the first time.]

Register your skill: After writing a skill file, add it to your settings.local.json in the permissions.allow array as {"skill": "my-skill-name"}. Without registration, invoking it returns "Unknown skill."

Building Block 3

Agents — Specialist Teammates

An agent is a Claude instance with a focused scope, specific tools, and hard constraints. Where skills are repeatable workflows, agents are domain specialists you can delegate work to — and trust that they'll stay in their lane.

Three rules for agent design

1Narrow scope wins. The more focused an agent's domain, the more reliably it works. "Code reviewer" is better than "general-purpose engineer." "Security scanner" is better than "code reviewer." Resist the urge to give agents everything.
2Hard constraints are not optional. Every agent needs explicit "you may not" rules. What files can it write? Can it call external APIs? Can it take production actions? Be explicit. An agent that can do anything is an agent you can't trust.
3Define done clearly. An agent without a Definition of Done will decide for itself when it's finished. That's usually wrong. Write the checklist it must satisfy before reporting complete.

When to create an agent vs. just prompting Claude directly

Create an agent when the domain is recurring (you'll use it many times across sessions)
Create an agent when you want hard constraints enforced — agents can't override their own rules
Create an agent when the work is independent (can be briefed without conversation context)
Create an agent when you want to run multiple parallel workstreams simultaneously
Just prompt directly for one-off tasks, exploratory conversations, or anything under 3 steps

.claude/agents/my-agent-name.md — Template

---
name: my-agent-name
description: >
  [Describe what this agent does and when to use it. Include
  the trigger phrases a user would use to invoke this agent.
  Be specific — a good description prevents misrouting.
  Example: "Security-focused code reviewer. Scans PRs for
  OWASP Top 10 vulnerabilities, secrets in code, and unsafe
  dependencies. Use for: 'security review this PR', 'check
  for secrets', 'OWASP scan'. NOT for: performance review,
  style issues, or architecture decisions."]
model: claude-sonnet-4-5-20250929
tools: [Read, Grep, Glob]
---

You are a specialist agent for [specific domain].
Your scope is intentionally narrow. Do one thing well.

## Your scope

You handle:
- [Exact list of what you do]
- [Be specific — name the files, domains, or decisions]

You do NOT handle:
- [What you explicitly pass back or refuse]
- [Related work that belongs to a different agent or the human]

## How to work

1. Read [the context files you need — list them explicitly]
2. [Core analysis or work — describe it step by step]
3. Validate your findings against [source of truth]
4. Report: [what format, what level of detail, what goes to a file vs inline]

## Hard constraints

- Never write to files outside your declared write scope
- Never take production actions, send messages, or modify
  shared state without explicit human approval
- Never expose secrets, credentials, or private data
  in your output
- All outputs are DRAFT until the human reviews and approves
- When uncertain, ask — do not guess and proceed

## Definition of Done

- [ ] [Criterion 1 — what "complete" looks like for your domain]
- [ ] [Criterion 2 — a verifiable output exists]
- [ ] Findings reported with evidence, not just conclusions
- [ ] Any blockers or uncertainties surfaced explicitly

## When you are stuck

If you cannot complete a step due to missing context, missing
access, or genuine uncertainty — stop and report the specific
blocker. Do not proceed on assumptions. Do not fabricate
context you don't have.

Tool selection guide — which tools does your agent actually need?

Read — reads files. Almost every agent needs this.
Grep — searches file contents with regex. Useful for analysis agents.
Glob — finds files by pattern. Useful for audit and inventory agents.
Write — creates or overwrites files. Give this only if the agent produces output files.
Edit — modifies existing files. More controlled than Write — prefer it when the agent modifies rather than creates.
Bash — runs shell commands. Use sparingly. Only when file tools can't do the job. High blast radius if misused.
WebSearch / WebFetch — calls the internet. Use only for research agents with clear scope.
Rule of thumb: start with the minimum tools needed and add only when a task genuinely can't be done without them.

Building Block 4

Memory — Persistent Learning

Memory is how Claude Code carries knowledge across sessions. Without it, every conversation starts fresh. With it, Claude remembers your preferences, your project context, and what did and didn't work last time.

The Four Memory Types

User

Who you are, how you work, your expertise. Helps Claude calibrate explanations and recommendations to you specifically.

Save when: role, preferences, expertise level, working style are mentioned

Feedback

What to do differently and what's working well. Prevents the same correction from being needed in every session.

Save when: "don't do that", "yes, exactly like this", or any strong approval/correction

Project

Active decisions, blockers, timelines, stakeholder context. What's happening in the project right now that shapes every decision.

Save when: decisions are made, blockers emerge, deadlines set, priorities shift

Reference

Where to find things in external systems — tickets, dashboards, Slack channels, wikis. Saves re-explaining location every time.

Save when: external resource location is relevant to recurring work

memory/MEMORY.md — The Index File

# MEMORY.md — Project Memory Index

# This file is auto-loaded. Keep entries to one line each.
# Format: - [Title](file.md) — one-line description of what's inside

## User
- [My Working Style](user_working_style.md) — how I like to collaborate, my expertise areas
- [My Tech Background](user_tech_background.md) — stack experience, what I know deeply vs. where I need support

## Feedback
- [Output Format Preferences](feedback_output_format.md) — HTML for reports, Markdown for docs, no em dashes
- [Response Style](feedback_response_style.md) — concise, no trailing summaries, match length to task

## Project
- [Current Sprint Focus](project_sprint_focus.md) — what we're building this week
- [Architecture Decisions](project_architecture.md) — key ADRs that shape every implementation

## Reference
- [Ticket Tracker](reference_tickets.md) — where to find issues, how we write tickets
- [Internal Tools](reference_tools.md) — dashboards, wikis, runbooks we reference regularly

memory/feedback_example.md — Individual Memory File Template

---
name: feedback-output-format
description: Preferred output formats and formatting rules that apply to all sessions
metadata:
  type: feedback
---

[Lead with the rule itself — what Claude should do or avoid]

Use dark-themed HTML files for any multi-section report, audit, or
status summary. Write to local/output/ and report the path. Keep
chat clean — don't paste the full content inline.

**Why:** [The reason the user gave — often a past incident or strong preference]
Previous sessions generated wall-of-text responses that were hard
to reference later. HTML files persist, are searchable, and can be
shared without reformatting.

**How to apply:** [When this guidance kicks in]
Any time the output is: a list of findings, a multi-step plan, a
comparison, a report, or anything longer than ~200 words of prose.
Exception: quick one-line answers can stay inline.

# Link related memories with [[their-name-slug]]
# [[feedback-response-style]]
# [[user-working-style]]

What NOT to save in memory

Code patterns, file paths, or project structure — read the files directly, they're always current
Git history or recent changes — git log is authoritative and always fresh
Debugging solutions or fix recipes — the fix is in the code; the commit message has the context
Anything already in CLAUDE.md — don't duplicate standing instructions in memory
In-progress task details or current session state — that's what session handoff notes are for
Secrets, credentials, or any sensitive data — never, under any circumstances

The Big Picture

How It All Connects

Each building block plays a distinct role in a session. Understanding the flow helps you place new ideas in the right building block — and notice when something is fighting its container.

CLAUDE.md

→

Loaded automatically at session start. Sets the stage: mission, constraints, style, context. Claude reads this before doing anything else.

Memory

→

Also injected at session start (via MEMORY.md index). Your persistent knowledge layer — preferences, project state, prior decisions.

/skill-name

→

Invoked by you during the session. Claude reads the skill file and executes the defined workflow — same sequence, every time.

Agent()

→

Delegated by Claude (or you) to a specialist. Runs in its own context with its own tools and constraints. Reports back when done.

Memory write

→

When something worth remembering happens, Claude writes it to memory/. Available in every future session automatically.

The key insight: CLAUDE.md and Memory handle continuity (what Claude knows walking into a session). Skills handle consistency (the same workflow, executed reliably). Agents handle focus (specialized work with guardrails). Together they turn a capable AI into a structured operating layer.

Getting Started

Your First Week

Don't try to build everything at once. Each day adds one piece. By the end of the week you have a working operating layer — and the intuition to keep building it.

Day 1

Write Your Mission Brief

Create CLAUDE.md with your mission, hard constraints, and style preferences. Don't perfect it — ship v1. You'll refine it as you notice what's missing.

→ CLAUDE.md exists and loads

Day 2

Build Your First Skill

Pick the task you repeat most often. Write a skill for it. Test it. Notice what the acceptance criteria need to say to make "done" unambiguous.

→ /my-skill works end-to-end

Day 3

Design Your First Agent

Identify a recurring task that benefits from isolation — a reviewer, a validator, a writer. Write the agent file. Start with Read-only tools. Add Write later.

→ .claude/agents/my-agent.md

Day 4

Start Your Memory System

Create memory/MEMORY.md. Write 2-3 memory files: your working style, one feedback preference, one project decision. Notice how the next session feels different.

→ Memory index + 3 files

Day 5

Run It End-to-End

Start a fresh session. Watch CLAUDE.md and Memory load. Run your skill. Invoke your agent. Notice what's missing. That gap is your Day 6 sprint.

→ Gaps identified, v2 planned

The pattern that actually sticks

The builders who get the most from this approach share one habit: they add to the system when they feel friction, not on a schedule. When you notice yourself giving Claude the same correction twice, write a memory entry. When you type the same multi-step instruction for the third time, write a skill. The system grows naturally from real pain points — and it stays lean because nothing gets added that isn't earning its place.

The goal isn't a perfect system on Day 1. The goal is a system you'll actually use and improve.

This resource is a gift — and an invitation

Everything here is drawn from real working experience with human-agentic collaboration. It's offered freely because the people who figure this out early have an extraordinary advantage — and that advantage shouldn't be locked behind a paywall or a consulting engagement.

If something here helped you, the best thing you can do is pass it forward. Build something good. Share what you learn. That's the whole point.

More resources, patterns, and open knowledge at rafikiaos.com.

The Builder's Guide
to Claude Code

What goes in it?

When to create a skill

Three rules for agent design

The pattern that actually sticks

This resource is a gift — and an invitation

Follow the signal.

The Architect's Playbook

The Agentic Systems Library

Take a pattern. Build something.

The Builder's Guideto Claude Code

What goes in it?

When to create a skill

Three rules for agent design

The pattern that actually sticks

This resource is a gift — and an invitation

Follow the signal.

The Architect's Playbook

The Agentic Systems Library

Take a pattern. Build something.

The Builder's Guide
to Claude Code