Five stages, 30 minutes total. Go from a blank slate to a Claude that knows your projects, follows your rules, remembers what you've taught it, and catches architectural mistakes before they happen.
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.
You end up repeating yourself. "I'm an SE." "This is a Salesforce project." "Don't use deprecated APIs." "Remember, we decided on approach B last week." Over and over.
This guide fixes that. You'll create a small set of files that Claude reads automatically at the start of every session. No plugins, no external tools, no coding required. Just 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, run claude --version. If you see a version number, you're good. If not, install Claude Code first at claude.ai/code.
When Claude Code starts a session, it looks for configuration files in a specific order. You don't need to "register" or "import" anything. Just put the files in the right place and Claude reads them automatically.
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 — 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. No configuration needed. Claude will know your name, your project, and your rules from the first message.
CLAUDE.md is project-specific. Rules files are global — they apply to every project on your machine. Security standards, coding conventions, how you want Claude to communicate. 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," "utilize," or "facilitate." 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 are always loaded, never 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 — don't build and find 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 — 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 your project's CLAUDE.md on top. If they conflict, rules files take priority. This means your security standards can't be overridden by project-specific settings.
A directory of markdown pages that Claude can look up when a task requires deeper context. Unlike CLAUDE.md, wiki pages are not loaded every session. They're pulled in on demand, which keeps your context window clean.
Think of CLAUDE.md as the table of contents. The wiki is the full book. Claude reads the table of contents every time, and opens specific chapters only when needed.
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 need to write all the pages yourself. When you learn something during a session — a tricky deployment step, a decision about architecture, a gotcha you hit — just tell Claude: "Add that to the wiki." Claude writes the page, updates the index, and it's 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 — it's already there.
Claude saves memory files in a project-scoped directory:
You don't need to know the exact path. Claude manages these files. MEMORY.md is the index, and Claude creates topic files for specific subjects (like deployment-gotchas.md or api-design-decisions.md).
When Claude makes a mistake:
Claude saves: "Always use API v2, not v1."
When you make a decision:
Claude saves: "Database: PostgreSQL (not MongoDB). Decision made [date]."
When Claude does something right:
Positive feedback compounds. Claude stops second-guessing what works.
Key insight: Memory works best for corrections and preferences. "Always use tabs, not spaces." "My team prefers verbose commit messages." "The staging environment URL is X." These are the kinds of things that save you time when Claude remembers 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 specific points in Claude's lifecycle. A SessionStart hook runs when you start a new session. You can use it to inject recent git activity, open issues, or other context that changes between sessions.
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": [
{
"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 — 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 runs at the beginning. A PreToolUse hook runs before Claude edits a file. This is where you catch architectural mistakes at the moment of action — before code is written, not after.
The concept: map file patterns to constraints. When Claude is about to edit salesforce.ts, the hook surfaces “Org62 = CLI only.” When Claude edits a deployment config, the hook surfaces the VPC constraint. The constraint appears in context at the moment it matters.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "python3 ~/.claude/hooks/scripts/architecture-guardrail.py",
"timeout": 3000
}
]
}
]
}
}
The script reads the file path from stdin (JSON with the tool input), checks it against a registry of constrained file patterns, and prints the relevant constraints + ADR references. Claude sees this output before proceeding with the edit.
DDR-001 principle: This applies a lesson from the Agentforce Agent Harness — “agents forget to remember.” Memory retrieval must be intrinsic (automatic), not voluntary (the agent chooses to look). Constraints rules load automatically. The hook fires automatically. The information is in Claude’s face when it matters, not buried in a wiki page it might not read.
Memory stores corrections. Wiki stores knowledge. Entity pages store people — a structured page per person that compounds across every interaction.
mkdir -p wiki/people
Two templates — one for internal colleagues, 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. -->
Seed them fast: ask Claude to search Slack profiles for your team and build the pages programmatically. One session maps your whole org tree — leaders, reports, coverage areas, Slack IDs. Then every meeting and collaboration appends to the timeline. Six months later, you have a relationship graph no CRM captures.
Knowledge bases get stale. Once a week (or whenever you think of it), do a quick review:
wiki/inbox.md — anything there worth promoting to a full page?
You can even ask Claude to help: "Review my wiki index and flag anything that looks outdated." Claude reads the files, checks dates, and reports back.
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.