Tips and tricks
A practical look at the project structure, config files, and workflow patterns that actually make a difference.
Most Claude Code tutorials show you the basics — install it, run a command, watch it write some code. That’s fine. But once you move past demos, you hit a wall. The default setup doesn’t scale. Projects get messy, context gets lost, and you spend more time managing the AI than building.
This article breaks down a production-ready Claude Code structure. Not theoretical. The kind of setup you’d actually want on a real project.
The project structure
A well-organized Claude Code workspace looks like this:
The .claude/ directory is where Claude’s behavior lives. Think of it as config for the AI, separate from your app code. This separation matters — it means you can version, share, and update AI workflows without touching your source files.
Start with CLAUDE.md
This file is Claude’s memory. Every session starts here. It answers: what is this project, how should I work, and what are the rules?
A solid CLAUDE.md covers:
- Tech stack — framework, language, key libraries
- Conventions — commit style, file naming, folder structure
- Architecture — where components live, how services talk to each other
- Security rules — no secrets in code, parameterized queries only
- Git workflow — branch strategy, PR checklist, when to run lint
Quick template: Tech Stack → Conventions → Architecture → Security. Four sections. Keep it under 300 words. Claude reads it every session — make it worth reading.
Skills: auto-activated workflows
Skills are the most underused part of Claude Code. Each skill is a folder inside .claude/skills/ with a SKILL.md file. Claude auto-activates them based on what you’re doing.
Typical skills on a real project:
- code-review/ — runs a checklist before PRs
- text-writer/ — handles copy, docs, and changelogs
- security-audit/ — scans for common vulnerabilities
- refactor/ — applies consistent patterns when cleaning up code
You can also invoke them directly with a slash command: /code-review, /security-audit, and so on. No setup beyond creating the folder and writing the instructions.
MCP servers: connecting Claude to your tools
MCP (Model Context Protocol) is how Claude talks to external services. You configure it in .mcp.json.
Useful MCP servers to start with:
- GitHub — pull requests, issues, repos
- PostgreSQL — direct database queries
- Slack — notifications and search
- Playwright — browser automation
- Filesystem — scoped file access
Always use environment variables for tokens. Never hardcode credentials in .mcp.json, and make sure that file is in your .gitignore.
Hook events
Hooks let you run logic at specific points in Claude’s workflow. They’re configured in settings.json and fire automatically.
- PreToolUse — block or modify before Claude runs a tool
- PostToolUse — trigger actions after writes (e.g. run lint)
- SessionStart — load context when a session opens
- PreCommit — scan for secrets before any commit
- Notification — send Slack alerts on key events
A practical pattern: use PostToolUse with a Write matcher to run npm run lint automatically after every file write. Catches problems immediately instead of at PR time.
Context management
Context windows fill up. Claude Code gives you rough guidance on what to do at each threshold:
- 0–60% — work normally
- 50–70% — watch usage, avoid large file loads
- 70–80% — run
/compactto compress history - 80%+ — run
/clearand start a fresh session
Good CLAUDE.md content reduces how much context you burn on orientation. If Claude already knows your stack and conventions, it doesn’t spend tokens figuring them out mid-task.
Getting started: the actual steps
- 1.
npm i -g @anthropic-ai/claude-code - 2.
cd your-project && claude - 3. Create
CLAUDE.mdwith your project conventions - 4. Add slash commands in
.claude/commands/ - 5. Configure MCP servers in
.mcp.json - 6. Add skills as your workflows grow
One thing: Don’t try to configure everything at once. Start with just CLAUDE.md and one skill. Add MCP servers once you know which tools you’re actually reaching for.
What makes this worth the setup time
The structure described here takes maybe an hour to put in place. What you get back is Claude that understands your project without being re-explained every session, custom workflows that activate automatically, and external tool access that doesn’t require copy-pasting between apps.
It’s not about using AI more. It’s about using it without friction.