Agentic AI

Stop Prompting Claude Code Better. Start Organizing It Better.

A single CLAUDE.md file gets you started, then quietly becomes the ceiling. Here's the directory structure I actually run — context, rules, commands, skills, agents, and hooks — and the two pieces that make multi-developer work with Claude Code collision-free.

FN
Fahid Nadeem
Jun 18, 2026 · 3 min read

Most developers are trying to prompt Claude Code better. The ones shipping fastest stopped doing that. They organize better instead.

A single CLAUDE.md file gets you started, then quietly becomes the ceiling. Every convention, integration, and guardrail ends up crammed into one file nobody wants to scroll through. So I gave Claude a real structure instead — a place for everything, so it understands how my team works before it writes a single line.

The full project structure — one file replaces something a human used to repeat for the model.

The Structure

your-project/
├── CLAUDE.md
├── CLAUDE.local.md
├── .mcp.json
└── .claude/
    ├── settings.json
    ├── settings.local.json
    ├── rules/
    │   ├── architecture.md
    │   ├── api-contracts.md
    │   └── testing-qa.md
    ├── context/
    │   ├── domain-glossary.md
    │   ├── data-model.md
    │   └── runbook.md
    ├── commands/
    │   ├── review.md
    │   └── fix-issue.md
    ├── skills/
    │   └── deploy/ (+ SKILL.md)
    ├── agents/
    │   ├── code-reviewer.md
    │   └── security-auditor.md
    └── hooks/
        └── validate-bash.sh

Each piece earns its place:

  • CLAUDE.md — the brain, loaded every session. Keep it under 200 lines.
  • .mcp.json — servers, databases, Slack integrations. Where it starts doing real work.
  • settings.json — permissions, models, hooks. Git-ignore the .local versions.
  • rules/ — conventions, split by topic: architecture, APIs, testing.
  • context/ — durable project knowledge: glossary, data model, runbooks.
  • commands/ — repeatable playbooks, like /review-pr or /fix-issue.
  • skills/ — auto-loaded by task match, so Claude stays light on context until it actually needs the skill.
  • agents/ — isolated specialists for review and audit, with no context pollution back into the main session.
  • hooks/ — guardrails that run before and after every tool call.

context/: The Knowledge That Usually Lives in One Person's Head

This is the folder that matters most and gets built least. Domain glossary, data model, runbooks — the stuff that normally only exists in a senior engineer's head, and that every new hire (or every fresh Claude session) has to have explained to them from scratch. Write it down once, and every new session starts already understanding the project instead of re-deriving it from the code.

task_group.md: What Makes Multi-Developer Work Actually Work

The second piece that matters more than people expect isn't even framework-specific — it's a convention. We split user stories into tasks per developer, and each developer's agent only touches and updates its own task group. No collisions, no merge chaos, everyone building in parallel, while a progress_tracking.md keeps the whole picture honest for whoever's checking status.

This is the part that turns Claude Code from "one person's tool" into something a team can run at the same time without stepping on each other.

Structure Is Leverage

This isn't overhead. It's leverage. Every file in this tree replaces something a human used to repeat for the model — explaining the architecture, re-stating the conventions, re-describing what "done" looks like for this codebase.

Start with CLAUDE.md. Then outgrow it on purpose.