Claude in a development project: files, agents and guardrails

An assistant like Claude is useful as soon as you give it context, and risky as soon as you let it do anything without guardrails. In my projects I therefore organised Claude Code like the rest of my tooling: readable, versioned files that say what is expected of it, what it may do and how to check its work. This article describes that organisation, with examples taken from my own working foundation, and the key distinction between what stays personal and what is shared in the repository.

The problem: an assistant that does not remember your rules

Without a framework, you repeat the same instructions in every session: language of comments, dependency management tool, commit message format, files not to open. And nothing stops the assistant from making a costly mistake, such as pushing code nobody asked it to push. A well-configured project has two goals:

• pass on the context once and for all, in files the assistant re-reads every session;
• set technical limits that do not depend on the model’s good will.

The six building blocks of a Claude Code project

Claude Code reads a context file at the root of the project and a configuration folder named .claude. Here is how I break them down.

Block	Role	Example in my setup
CLAUDE.md	Project context and rules, in free text, re-read every session	Universal working rules: answers in French, commits in Conventional Commits format, never push without an explicit request
Rules (rules)	Topic-specific instructions kept in separate files	A “git, commits and versions” rule shared by all projects; code convention rules specific to Python utilities
Agents	Specialised assistants with their own instructions and tools	A security review agent that reads a diff without changing anything, one that runs the tests, one that audits dependencies, one that keeps the documentation up to date
Commands	Procedures triggered on demand	A commit command that splits the changes, writes the message in the right format and refuses to bypass checks
Hooks	Scripts run automatically before or after an action of the assistant	A hook that blocks commits on the main branch and dangerous git options; another that refuses to write an apparent secret into a tracked file
Skills	Detailed know-how, loaded only when the task calls for it	A web best-practices guide, used for website projects

What is a rule and what is a guardrail

The most useful distinction I have kept is this: a rule written in CLAUDE.md is a request, a hook is a constraint. I ask the assistant never to push without my agreement, but it is the hook on git commands that actually prevents it from forcing a push or bypassing the checks before a commit. The permissions in the settings file play the same role: some read-only commands (repository status, history) are allowed by default, while other operations are refused whatever happens.

• What must always be respected (secrets, git history, sending to production): a hook or a permission.
• What is a matter of preference or style (language, tone, naming conventions): a rule or the CLAUDE.md.
• What is long and specialised (security review, dependency audit): an agent or a skill, so as not to weigh down every session’s context.

Personal to the developer, or shared in the repository?

Not everything belongs in the repository. Claude Code distinguishes several levels, and I sort them like this:

• Shared with the team, versioned in the repository: the project’s CLAUDE.md, its rules, agents, commands, hooks and the common settings file. Anyone cloning the project gets the same working framework.
• Personal to the developer, outside the repository: my general preferences, my local settings and the memory the assistant builds up about how I work. They stay on my machine and are not passed to a client or a colleague.
• Never read or written: secret and environment files. The foundation’s rules forbid displaying them without need, and a hook refuses to write an apparent secret into them.

This separation has a practical consequence: a project I deliver to a client contains its working framework, usable without me, but never my personal preferences.

My organisation: a common foundation and autonomous projects

I work on several kinds of projects: websites, applications hosted on the same server, small Python utilities. The universal rules are written once, in a common foundation. But Claude Code only reads the configuration folder of the project that is open: it does not go looking for its rules elsewhere.

So I chose copying over linking. The foundation contains:

• a folder of common sources (rules, agents, commands, hooks);
• profiles by type of project (web, application, Python utility), which add what is specific to that type;
• a registry that states, for each project, which profiles apply;
• a synchronisation script that copies everything into each project.

Each project therefore stays autonomous: it can be cloned on its own, on another machine, and work without the foundation. The synchronisation follows three rules: a missing or identical file is copied; a copied file that was never modified is updated at the next synchronisation; a file the project has specialised is kept and flagged as different. A project can thus adapt a rule without it being overwritten, and I never edit a managed file by hand, since it would be replaced.

Changing a common rule always follows the same path: I edit it in the foundation, run the synchronisation as a dry run to see what would change, apply it, then validate the change with a commit in each affected project.

A concrete example: the git guardrail

Commit instructions are a good textbook case. The CLAUDE.md and the git rule specify the expected format (type in English, description in French), the ban on bypassing checks and the ban on pushing without a request. The matching hook then refuses, before anything runs, a forced push or a commit that disables the checks. And the commit command chains the steps: review the changes, propose a split into short commits, write the message, let the automatic checks run. The rule explains, the command guides, the hook protects.

The link with the Claude Architect Foundations certification

In 2026 I earned the Anthropic Claude Architect Foundations certification, which I mention on my About page. This article does not reproduce its curriculum: it describes how I use Claude in my daily work as a developer. What I take from that approach is the idea of treating the assistant as a component of a system, with a defined context, limited tools, checks on its output and a human who keeps the decision.

Where to start in your project

1. Write a short CLAUDE.md: test and launch commands, code conventions, what must never be done.
2. Move topic-dependent instructions into separate rules.
3. Turn every really important prohibition into a hook or a denied permission.
4. Create an agent only for a task that comes back often and needs a specialised eye.
5. Decide from the start what is shared in the repository and what stays personal.

In short

Good use of Claude in a project depends less on the model than on the organisation around it: a clear context, readable rules, technical constraints for sensitive points and a clean separation between personal and shared. That framework is what makes the work repeatable from one session to the next and from one project to the next. For the working method around these projects, also read from need to delivered product: my working methodology.