Five stages, about 30 minutes of work. By the end, Claude starts every session already knowing your projects, following your rules, remembering what you've taught it, and catching architectural mistakes before they land.
Every time you start a Claude Code session, Claude has no idea who you are, what you're working on, or what you told it yesterday. It's a brilliant collaborator with total amnesia.
So you end up repeating yourself every session: "I'm an SE," "this is a Salesforce project," "don't use deprecated APIs," "remember, we decided on approach B last week."
This guide fixes that. You'll create a small set of files that Claude reads on its own at the start of every session, with no plugins, no external tools, and no code to write. Just the right files, in the right places, with the right content.
Installed as CLI (claude) or VS Code extension. Either works.
Any folder where you regularly use Claude Code. Could be a Salesforce project, a Node app, anything.
Stages 1–4 take about 30 minutes total. Stage 5 is optional and takes another 15.
Quick check: open your terminal and run claude --version. A version number means you're set. If nothing comes back, install Claude Code first at claude.ai/code.
When Claude Code starts a session, it looks for configuration files in a specific order, so there's nothing to "register" or "import." You just put the files where they belong, and Claude reads them on its own.
A markdown file in your project root that Claude reads at the start of every session. Think of it as a briefing document you'd hand a new teammate on their first day. "Here's who we are, here's what we're building, and here's how we work."
Navigate to your project root in the terminal and create the file:
cd ~/your-project touch CLAUDE.md
Open CLAUDE.md in your editor and paste this. Replace the bracketed content with your own details:
# Project Context ## Owner - Name: [Your name] - Role: [Your title and team, e.g. "Senior SE, Enterprise West"] - Context: [One line on how you use Claude Code] ## What This Project Is [2-3 sentences describing the project. What does it do? Who is it for? Include the tech stack if relevant: Salesforce, Node.js, Python, etc.] ## Rules (Always Follow) 1. Never hardcode IDs, credentials, or environment-specific values 2. Explain what you're changing and why before making edits 3. Don't delete files or code without asking first 4. Keep responses concise and skip the preamble 5. [Add your own rules here] ## Current Work - [What you're actively working on right now] - [Any open questions or blockers] ## Preferences - [How you like Claude to communicate: brief? detailed? bullets?] - [Any output style preferences: "write like an SE, not a marketer"]
What happens now: the next time you start Claude Code in this project directory, it reads CLAUDE.md automatically, with no configuration needed. From the first message, Claude knows your name, your project, and your rules.
CLAUDE.md is project-specific, but rules files are global, so they apply to every project on your machine. Think security standards, coding conventions, and how you want Claude to talk to you. Write them once, and Claude follows them everywhere.
mkdir -p ~/.claude/rules
This one sets basic guardrails for how Claude writes and modifies code:
# Coding Standards ## Before making changes - Read the existing code first. Match the patterns already in the codebase. - Explain what you plan to change and why before editing. - Prefer small, reversible changes over large rewrites. ## Code quality - Write tests for new functionality. - Handle errors explicitly. Never swallow exceptions silently. - No hardcoded IDs, URLs, secrets, or environment-specific values. - Add comments only when the "why" isn't obvious from the code. ## Safety - Never delete files, functions, or data without asking first. - Don't push to remote repositories unless explicitly asked. - Don't modify git history (no force push, no rebase) without permission. - Never read or expose .env files, secrets, or credentials.
This controls how Claude talks to you:
# Communication Rules ## Response style - Be direct. Start with the answer, then explain if needed. - Keep responses concise. No filler phrases or throat-clearing. - Use bullets and short paragraphs over walls of text. - When I ask a yes/no question, start with yes or no. ## Things to avoid - Don't start responses with "Great question!" or "Sure, I'd be happy to..." - Don't repeat my question back to me. - Don't add disclaimers unless there's a genuine risk. - Don't use jargon like "leverage" or "utilize." Use plain words.
This one prevents architectural mistakes, the kind where Claude builds code that can never work because it violates a hard infrastructure boundary. These constraints stay loaded in every session and never get cut from context:
# Infrastructure Constraints ## Hard Rules (never override) - [Service A] can only be accessed via [method]. No direct API/JWT/OAuth. - [Database] is VPC-only. Cannot be reached from local machines. - [Deployment target] requires [specific process]. No shortcuts. ## Decision Gate Before adding new auth, connectors, or infrastructure code: 1. Check this file first 2. Check decisions/ directory for relevant ADRs 3. Verify MCP or existing tooling doesn't already connect 4. If unsure, ask instead of building and finding out later
Why this matters: Without constraints rules, Claude will pattern-match on local code and build auth/integration paths that look correct but violate infrastructure realities. I learned this the hard way: Claude built an entire JWT authentication flow to a system that had no Connected App and never could have one. The constraint rule would have prevented it before a single line was written.
If you work on Salesforce projects, add platform-specific guardrails:
# Salesforce Development Rules ## Apex - All Apex must be bulk-safe. Never perform SOQL or DML inside loops. - One trigger per object. Keep triggers thin and put logic in service classes. - Enforce CRUD/FLS and sharing rules. State the sharing model for every class. - Handle governor limits explicitly. Comment when approaching known limits. ## General - Prefer declarative solutions (Flow, validation rules) over code when possible. - Use Lightning Web Components for UI work. No new Aura components. - Never assume org configuration. Check metadata before proposing changes. - Never rename standard fields or objects.
How rules and CLAUDE.md work together: Claude loads all ~/.claude/rules/*.md files first, then layers your project's CLAUDE.md on top. If the two ever conflict, the rules files win, so a project-specific setting can never quietly override your security standards.
It's a directory of markdown pages Claude can look up when a task needs deeper context. Unlike CLAUDE.md, these pages stay out of the session by default and get pulled in only on demand, which keeps your context window clean.
Think of CLAUDE.md as the table of contents and the wiki as the full book. Claude reads the contents every time, then opens a specific chapter only when the work calls for it.
cd ~/your-project mkdir -p wiki touch wiki/index.md touch wiki/inbox.md
The index is a catalog of all wiki pages. Claude uses it to find what it needs:
# Wiki Index Master catalog of reference pages. Claude reads this to find context for specific tasks. ## Pages | Page | Description | Last Updated | |------|-------------|--------------| | [architecture.md](architecture.md) | System architecture and design decisions | [date] | | [api-patterns.md](api-patterns.md) | API conventions and integration patterns | [date] | | [deployment.md](deployment.md) | How to deploy, environments, rollback steps | [date] | ## Inbox See [inbox.md](inbox.md) for items to be processed into wiki pages.
The inbox is a scratch pad. When Claude learns something during a session, it drops a note here for later processing:
# Wiki Inbox Items captured during sessions. Review periodically and promote to full wiki pages. <!-- New items go below this line -->
This is the key part. Add a table to your CLAUDE.md that tells Claude which wiki page to read for which kind of work:
## Knowledge Base
Reference pages are in `wiki/`. Load the relevant page when a task requires it.
| Work Context | Wiki Page |
|-------------|-----------|
| Architecture decisions | `wiki/architecture.md` |
| API work | `wiki/api-patterns.md` |
| Deploying changes | `wiki/deployment.md` |
How the wiki grows: you don't have to write every page yourself. When you learn something during a session, like a tricky deployment step or an architecture decision or a gotcha you just hit, tell Claude to add it to the wiki. It writes the page, updates the index, and leaves it there for next time.
Claude Code has a built-in memory system. When you correct Claude, give it feedback, or make a decision it should remember, it can save that to a MEMORY.md file that persists across sessions. You don't need to install or configure anything, since it's already there.
Claude saves memory files in a project-scoped directory:
You don't need to know the exact path, since Claude manages these files for you. MEMORY.md is the index, and Claude spins up topic files for specific subjects (like deployment-gotchas.md or api-design-decisions.md).
When Claude makes a mistake:
Claude saves the rule "always use API v2 and avoid v1" for every session after this one.
When you make a decision:
Claude saves the decision that this project runs on PostgreSQL over MongoDB, stamped with the date it was made.
When Claude does something right:
Positive feedback compounds, so Claude stops second-guessing the things that already work.
Key insight: memory works best for corrections and preferences. Think "always indent with tabs," "my team prefers verbose commit messages," or "the staging environment URL is X." Those are the facts that save you real time once Claude holds onto them.
If Stages 1–4 are working for you, these additions take your setup further. None of them are required, but each one reduces friction.
A hook is a script that runs automatically at set points in Claude's lifecycle. A SessionStart hook, for instance, fires when you open a new session, and you can use it to inject recent git activity, open issues, or anything else that shifts from one session to the next.
Create the hook script:
#!/bin/bash # Session init hook: shows recent git activity at session start echo "## Recent Activity" echo "" # Show last 5 commits echo "### Last 5 Commits" git log --oneline -5 2>/dev/null || echo "Not a git repo" echo "" # Show uncommitted changes CHANGES=$(git status --short 2>/dev/null) if [ -n "$CHANGES" ]; then echo "### Uncommitted Changes" echo "$CHANGES" fi
Make it executable and register it in your Claude settings:
chmod +x ~/.claude/hooks/session-init.sh
Then add this to your ~/.claude/settings.json (create it if it doesn't exist):
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "~/.claude/hooks/session-init.sh"
}
]
}
]
}
}
When you make a critical architecture decision, capture the why, not just the what. ADRs prevent future sessions from re-deriving decisions and getting them wrong.
mkdir -p decisions touch decisions/INDEX.md
Each ADR captures the decision, what you rejected, and why:
# ADR-001: [Title of decision] Status: Accepted Date: [YYYY-MM-DD] ## Context [What problem were you solving? What constraints exist?] ## Decision [What you decided to do] ## Alternatives Rejected | Option | Why Rejected | |--------|-------------| | [Alt A] | [Reason] | | [Alt B] | [Reason] | ## Consequences [What this means going forward, including constraints it creates]
When to write an ADR: When choosing between approaches where the wrong choice produces dead code, violates infrastructure constraints, or would take significant effort to reverse. Not every decision needs one, just the ones where the reasoning needs to survive across sessions.
A SessionStart hook fires at the beginning of a session, while a PreToolUse hook fires before Claude edits a file. That's where you catch an architectural mistake at the moment of action, while the code is still unwritten.
One pattern is mapping file patterns to constraints. When Claude is about to edit salesforce.ts, a hook can surface “internal CRM = CLI only.” Edit a deployment config instead, and it can surface the VPC constraint. Either way, the constraint lands in context at the moment it matters.
Both editions of the starter kit ship a guardrail of this kind for shell commands, and setup wires it for you. It denies destructive commands such as a force-push to main. This is its entry with an optional timeout added, and a hook's timeout is in seconds:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "python3 ~/.claude/hooks/scripts/guardrail.py",
"timeout": 10
}
]
}
]
}
}
The script reads the tool call from stdin as JSON and answers in JSON. To block a call it returns a hookSpecificOutput object with permissionDecision set to deny and a permissionDecisionReason. To nudge instead, it returns additionalContext in that same object, and Claude sees it before proceeding.
DDR-001 principle: this applies a lesson from the Agentforce Agent Harness: “agents forget to remember.” Memory retrieval has to be intrinsic and automatic rather than voluntary, where the agent has to choose to go look. So the constraints rules load on their own and the hook fires on its own, which puts the information in Claude’s face at the moment it matters instead of leaving it buried in a wiki page it might never open.
Memory stores your corrections and the wiki stores your knowledge. Entity pages store people, one structured page per person that compounds across every interaction you have with them.
mkdir -p wiki/people
Two templates, one for internal colleagues and one for external contacts:
# {Name} ## Profile - Title: - Team/OU: - Reports to: - Location: - Slack: {ID} | {email} ## Working Style ## Current Focus ## Territory / Coverage --- ## Timeline <!-- Append after every interaction. Newest at top. -->
You can seed them fast by asking Claude to search Slack profiles for your team and build the pages programmatically. A single session maps your whole org tree: leaders, reports, coverage areas, Slack IDs. From then on, every meeting and collaboration appends to the timeline, and six months later you're holding a relationship graph no CRM captures.
Knowledge bases get stale, so once a week (or whenever you think of it) run a quick review:
wiki/inbox.md: anything there worth promoting to a full page?
You can even hand this off to Claude by asking it to review your wiki index and flag anything that looks outdated. It reads the files, checks the dates, and reports back to you.
Where to go from here:
.claude/commands/), MCP servers for connecting external data sources, and PreToolUse hooks for architecture guardrails
Built by John Tehrani, Principal Solutions Engineer, Salesforce
Part 1 of 5: Foundation. Written collaboratively with Claude Code.