AI Club

Understanding The New Claude Code Conventions, Be a Better AI Coder

Hazem Abbas

30 Apr 2026 — 9 min read

The era of the "chat box" AI is over. If you are still opening a browser tab, pasting 200 lines of code, and asking a LLM to "fix the bug," you aren't just behind, you are working ten times harder than you need to.

I’ve spent the last few months living inside Claude Code. It isn't a plugin. It isn't a wrapper. It is a terminal-based agent that treats your codebase like a living organism. But the real secret sauce isn’t just the model, it’s the Architecture.

Most developers treat AI instructions like a temporary sticky note. Claude Code treats them like a blueprint. If you want to stop fighting your AI and start leading it, you need to master the Claude Project Structure.

Here is exactly how to set up your environment to build better systems, faster.

1. The Soul of the Project: `CLAUDE.md`

Think of CLAUDE.md as the onboarding manual for your AI agent. In traditional development, a new engineer spends three days reading documentation and setting up their environment. Claude does it in three milliseconds.

Why it matters: Without this, Claude is guessing. It doesn't know if you prefer Functional Programming over OOP, or if you use Vitest instead of Jest.

What goes inside:

Tech Stack: Explicitly list your versions (e.g., Next.js 15, Tailwind v4, Directus SDK).
Architecture: Define your patterns. Do you use the Service Layer pattern? Are you strict about the "Fat Model, Thin Controller" rule?
Standard Commands: List your pnpm or composer scripts so Claude knows how to run tests or build the app without asking you.

Pro-Tip: Use CLAUDE.local.md for your personal overrides that you don’t want to commit to Git, like specific local paths or experimental flags.

2. The Global Connectivity: `mcp.json`

The Model Context Protocol (MCP) is the bridge between Claude and the outside world. This file is where you configure how Claude talks to your Jira tickets, your Slack channels, or even your production database.

Why it is important:

Most AIs are trapped in a vacuum. By configuring mcp.json, you allow Claude to pull context from a GitHub Issue or check a Sentry log before it suggests a fix. It transforms the agent from a "code writer" into a "troubleshooter."

3. Governance and Safety: `settings.json`

In a professional environment, you can’t give an AI agent a blank check. settings.json is where you define the boundaries.

The Essentials:

Permissions: Can Claude execute shell commands? Can it read files outside the project root?
Model Selection: Choose between claude-3-5-sonnet for speed or claude-3-opus for deep architectural reasoning.
Tool Access: Enable or disable specific capabilities like web searching or image processing.

4. The Guardrails: `rules/`

This is where you move from "asking for code" to "enforcing standards." The rules/ directory contains modular Markdown files that Claude reads before every task.

How to structure it:

rules/code-style.md: "Always use arrow functions. Never use var. Use TypeScript strict mode."
rules/testing.md: "Every new feature requires a corresponding Pest test in the tests/Feature directory."
rules/api-conventions.md: "All API responses must follow the JSend specification."

By splitting these into modular files, you keep the context window clean. Claude only pulls the rules it needs for the specific file it is touching.

5. Automation at Scale: `commands/`

We all have those "repeatable workflows" that involve five different terminal commands. In Claude Code, you can turn these into custom slash commands.

Instead of typing:

"Run the migrations."
"Seed the database."
"Start the dev server."

You create a commands/refresh-db.md file. Now, you just type /refresh-db in the terminal, and Claude executes the entire sequence. It’s a CLI for your CLI.

6. Context Management: `skills/`

The biggest enemy of AI performance is context bloat. If you give Claude 50,000 lines of irrelevant documentation, its reasoning gets "fuzzy."

The skills/ folder allows you to define specialized capabilities that only load when a specific task is triggered. For example, a "Deployment Skill" only loads when you are working in the infra/ folder. This keeps the agent’s "brain" lightweight and focused.

7. The Specialist Squad: `agents/`

Sometimes, a single agent isn't enough. You need a second pair of eyes. The agents/ directory allows you to define sub-agents with specific personas.

agents/security-auditor.md: A persona focused entirely on finding SQL injection risks or leaked API keys.
agents/performance-expert.md: An agent that only looks at query execution times and memory leaks.

When you finish a feature, you can tell Claude: "Have the security-auditor agent review my last 3 commits." It creates an isolated context window specifically for that role.

8. The Automation Chain: `hooks/`

This is the ultimate level of professional development. Hooks are event-driven scripts that run before or after Claude uses a tool.

The "Safety First" Workflow:

Imagine a pre-hook script that runs eslint every time Claude tries to save a file. If the code doesn't pass linting, the hook blocks the operation and tells Claude to fix the errors first. You never have to manually fix a semi-colon again.

Why This Changes Everything for You

As a developer who balances medical data, horse-riding instruction software, and complex AI marketplaces, my time is my most valuable asset. Before I adopted this architecture, I was a "babysitter." I had to watch the AI to make sure it didn't break my Laravel conventions or use the wrong React hook.

Now? I am a conductor.

I spent one day setting up these files. Now, when I start a new feature for a project like TakeAsIstan, I don't explain the database schema. I don't explain the UI library. I just say: "Build the 'Make an Offer' component," and Claude follows the rules/, respects the CLAUDE.md stack, and validates the code through the hooks/.

Getting Started: The Migration Path

If you are just starting with Claude Code, don't try to build all eight directories tonight. Start here:

Create CLAUDE.md first. This gives you the biggest immediate ROI.
Add rules/code-style.md. Stop repeating yourself about syntax.
Build one command/. Automate your most annoying daily task.

The goal isn't just to write code faster. The goal is to build better systems. Laravel taught us the value of "Convention over Configuration." Claude Code brings that same philosophy to the AI era.

Stop prompting. Start architecting.

Tips for the Transition: Choosing the Right Tool

Use [X]	Instead of [Y]	Because...
`CLAUDE.md`	Long System Prompts	System prompts are ephemeral; `CLAUDE.md` is version-controlled and grows with your project.
`rules/`	Manual Review	Rules prevent bugs before they are written; reviews only find them after they exist.
`hooks/`	CI/CD alone	Hooks give you instant feedback in the terminal, saving you 10 minutes of waiting for a GitHub Action to fail.
`skills/`	Large Contexts	Skills save you money on token costs and keep Claude's reasoning sharp by removing "noise."

What’s the first custom slash command you’re going to build? For me, it was a /review command that runs a security audit and a performance check simultaneously. It turned a 30-minute manual check into a 15-second automated win.

Go build something clean.