The builder’s guide
Give your work a structure.
Roles, instructions, memory and reusable skills. Build a working system one careful layer at a time.
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 logis 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.
Keep exploring
