jbarbier/CLAUDE.md

What it solves

This project provides a comprehensive, opinionated set of instructions (a "contract") for coding agents like Claude Code, Cursor, and Gemini CLI. It prevents agents from defaulting to mediocre behavior—such as skipping tests, inventing libraries, or asking for permission for tasks they should handle independently—by establishing a standing set of rules for how the agent should think, write code, and communicate.

How it works

The project consists of a single file, CLAUDE.md, which is loaded into the model's context at the start of every session. This file acts as a system prompt or standing contract that overrides the agent's default behavior. To ensure compatibility across different tools, the author suggests using symlinks (e.g., linking CLAUDE.md to AGENTS.md or GEMINI.md) so that a single source of truth is maintained for multiple AI coding tools.

Who it’s for

Developers who use AI coding agents and want to higher-quality, more predictable output by providing the agent with a strict set of operational guidelines.

Highlights

• Cross-Tool Compatibility: Supports Claude Code, OpenAI Codex CLI, Cursor, and Gemini CLI through a standardized naming convention and symlinks.
• Coded Branching Rule: Includes a tested set of shell commands to manage git worktrees, ensuring multiple agent sessions don't conflict in the same repository.
• Multi-Agent Workflows: Incorporates a "fan-out + harsh critic" loop for high-quality output and a self-rating rule for iterative improvement.
• Modular Design: The instructions are categorized into sections (e.g., Task Sizing, Safety, Completion Status) that users can delete or keep based on their specific project needs and stack.
• Verified Commands: The repository includes a test suite to ensure that the shell commands provided within the the instructions are functionally correct.