The Coding Mermaid 🧜‍♀️

Posted on Apr 16

🦄 Master Your Workflow: Anatomy of the .claude Folder

#webdev #claude #ai #programming

✨ Hey everyone! Have you seen that .claude folder appearing in your projects and felt like it was a "black box"? Don't let it scare you! Just like learning JavaScript, it takes a little bit of curiosity to turn it into your best friend.

The .claude folder is the control center. When you configure it properly, Claude stops guessing and starts following your rules. Let's break it down! ✨

🏠 1. The Two Homes (Global vs. Project)

Before we dive into the files, remember there are two places where these settings live:

Project-level (/your-project/.claude): This is for the team. You commit this to Git so everyone follows the same standards.

Global-level (~/.claude/): This is just for you. It stores your personal coding style and your "Auto-memory" across all your different projects.

📝 2. CLAUDE.md: Your Project's Instruction Manual

This is the most important file! It's the first thing Claude reads.

What to include:

Build commands, test commands, and lint commands
Key architectural decisions
Non-obvious "gotchas" (like "We use strict TypeScript")
Import conventions and naming patterns

Mónica's Advice: Keep it under 200 lines! If it's too long, Claude gets overwhelmed — just like we do when we study for 8 hours straight without a break. ☕️

🛡️ 3. settings.json: Your Safety Guardrails

This file controls what Claude is allowed to do. I love this because it gives us peace of mind! You can use an allow list for things you trust and a deny list for things that are private.

Example settings.json:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Read",
      "Write",
      "Edit"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

Note: By denying .env, you ensure your API keys and secrets stay safe! 🔐

Anything not in either list? Claude will ask before proceeding. That middle ground is intentional — it's your safety net!

📂 4. The Rules Folder: Scaling Your Wisdom

When your CLAUDE.md gets too crowded, move things into .claude/rules/. You can have:

testing.md – Rules for Jest/Vitest
api-conventions.md – Rules for API design
code-style.md – Rules for formatting and patterns

Path-scoping magic: You can tell Claude to only read component-standards.md when working inside the src/components folder!

---
paths:
  - "**/*.test.ts"
  - "**/*.spec.ts"
  - "tests/**/*"
---
# Testing Standards

- Use describe blocks to group related tests
- Test IDs must use data-testid attribute, not classes or IDs
- Mock external API calls — never hit real endpoints in tests
- Each test file must clean up side effects in afterEach
- Snapshot tests require a comment explaining what they verify

🤝 The Power of Ownership: Modular Rules

One of the biggest mistakes teams make is having one giant, messy CLAUDE.md. It becomes a "junk drawer" that nobody wants to clean.

The Solution: Use the .claude/rules/ folder to assign Topic Ownership.

Instead of one file, you have:

rules/accessibility.md — Owned by the A11y specialist
rules/api-design.md — Owned by the Backend Lead
rules/testing-standards.md — Owned by the QA or Testing enthusiast

Why this makes life easier:

✅ No "Merge Conflicts" in your head: When the API lead wants to update a convention, they only edit their file. They don't have to scroll through 500 lines of CSS rules to find it.

✅ Clear Responsibility: If Claude starts writing bad tests, the team knows exactly which file needs a "tweak" and who to talk to about improving that standard.

✅ Path-Specific Activation: Rules only activate when Claude is actually working in the relevant folder. This keeps Claude's brain "light" and focused!

⚡ 5. Commands vs. Agents (Your Secret Weapons)

Commands (.claude/commands/): These are manual. You type /project:review and Claude executes a specific workflow you designed.

Example command (review.md):

---
description: Review current changes for code quality and best practices
---
## Files Changed

!`git diff --stat origin/develop...HEAD`

## Full Code Changes

!`git diff origin/develop...HEAD`

Analyze the changes above and check for:
1. Potential bugs or logic errors
2. Performance concerns (unnecessary loops, heavy operations)
3. Inconsistent code style with our conventions
4. Missing error handling or edge cases
5. Opportunities for simplification or refactoring

Provide specific line-by-line feedback with file paths.

Agents (.claude/agents/): These are smart. Claude watches the conversation and can trigger them automatically based on their description field — so if you ask about accessibility, an agent scoped to that will kick in without you having to call it explicitly.

Example agent (.claude/agents/accessibility-audit.md):

---
name: accessibility-audit
description: Use when user asks about a11y, WCAG compliance, or accessibility improvements
tools: Read, Grep, Glob
---
Perform a comprehensive accessibility audit:

1. Check for missing alt text on images and icons
2. Verify proper heading hierarchy (h1 → h2 → h3, no skipping)
3. Ensure keyboard navigation works (focus states, tab order)
4. Validate ARIA labels on interactive elements
5. Check color contrast ratios meet WCAG AA standards

Provide actionable recommendations with file paths and specific line references.

🤖 6. Agents: Specialized Personas

Sometimes a task is so complex it needs a specialist. Agents live in .claude/agents/ and can act as focused personas with a specific model, toolset, and set of instructions.

Example agent (code-reviewer.md):

---
name: code-reviewer
description: Expert code reviewer. Use when reviewing PRs or validating implementations.
model: claude-sonnet-4-5
tools: Read, Grep, Glob
---
You are a senior code reviewer focused on correctness and maintainability.

When reviewing:
- Flag bugs, not just style issues
- Suggest specific fixes
- Check for edge cases
- Note performance concerns when they matter

Pro tip: You can tell the Agent to use a faster, cheaper model (like Claude Haiku) for simple tasks to save on credits!

🏠 7. The "Secret Garden": Understanding .local Files 🌸

In a team, we share everything. But we all have our own little habits, right? Maybe you prefer a specific terminal theme, or you want Claude to always use a specific shortcut that only works on your computer.

That's where CLAUDE.local.md and settings.local.json come in.

🤫 Why use CLAUDE.local.md?

This file lives in your project root, but here's the magic: it is automatically gitignored. This means you can give Claude personal instructions that your teammates will never see.

Personal Preferences:

"Claude, when I ask to run tests, always use the --watch flag because I like to see them update in real-time."

Machine Specifics:

"On this laptop, my local database is on port 5433, not 5432."

Learning Style:

"I'm still learning TypeScript, so please explain any complex types you use in the comments just for me."

🛡️ settings.local.json: Your Personal Security Guard

While the team's settings.json might allow general commands, you might want stricter rules for yourself.

If you have a folder named /private-notes that isn't in the main repo, you can add it to the deny list in your local settings so Claude never accidentally reads your personal thoughts!

📚 The Three Voices: A Quick Summary

CLAUDE.md (The Team's Voice): Shared rules. Everyone follows these. It's the "Source of Truth" for the codebase. 🤝

CLAUDE.local.md (Your Private Voice): Personal overrides. Use this for your own workflow habits or local machine settings. It stays on your computer and never gets pushed to GitHub. 🤫

~/.claude/CLAUDE.md (The Global Voice): This is the "Mónica Rulebook." Put things here like "Always use functional components in React" or "Be concise and use emojis". These rules will follow you into every project you open! 🌍

🚀 Quick Start Guide

If you're starting from scratch, here's a progression that works well:

Run /init inside Claude Code to generate a starter CLAUDE.md
Add .claude/settings.json with allow/deny rules appropriate for your stack
Create 1-2 commands for workflows you do most (code review, issue fixing)
As your CLAUDE.md grows, start splitting instructions into .claude/rules/ files
Add ~/.claude/CLAUDE.md with your personal preferences

💜 Mónica's Pro-Tip:

"Treat your .local files like your self-care routine. They are there to make your life easier and your workspace feel like home. Don't be afraid to tell Claude exactly how you like to work — he's there to support you, not just the project!"
💜🦄

🌟 The Key Insight

The .claude folder is really a protocol for telling Claude who you are, what your project does, and what rules it should follow. The more clearly you define that, the less time you spend correcting Claude and the more time it spends doing useful work.

CLAUDE.md is your highest-leverage file. Get that right first. Everything else is optimization.

Start small, refine as you go, and treat it like any other piece of infrastructure in your project: something that pays dividends every day once it's set up properly. ✨

What's your favorite .claude folder trick? Drop a comment below! 👇

Happy coding! 🦄💖

DEV Community