As someone who balances the precision of medical practice with the structural logic of system architecture, I’ve always viewed code as a living organism. When I’m building a project like AI shopping assistant or the MOTOID medical system, every line of code serves a vital function. But lately, I’ve noticed a recurring fever in the development community, one I’ve experienced firsthand.
We’ve invited a new resident into our “operating rooms”: Antigravity.
It is, without a doubt, the most brilliant assistant we’ve ever had. But there’s a problem I’ve seen many developers—including myself—struggle with. You ask Antigravity to perform a minor “suture” on a UI component, and by the time you look back at the screen, it has decided to perform a full-body reconstruction. It refactors your directory structure, “optimizes” configurations it wasn’t supposed to touch, and implements features you never asked for.
In medicine, we call this “scope creep” during surgery, and it’s dangerous. In software, it’s a productivity killer that turns a 5-minute fix into a 2-hour session of reverting Git commits.
As a software architect and longtime Linux advocate, I believe in systems of control. We shouldn’t blame the agent for being ambitious; we should blame the lack of a “Medical Board” to govern its actions. If you don’t define the boundaries, the agent assumes its mandate is infinite.
In this post, I’m going to show you how I’ve used my experience in building complex AI-driven ecosystems to “tame” the agent. We’re going to look at the mechanical reason why Antigravity goes rogue and how to implement a Project Constitution—the CLAUDE.md file—that forces the agent to act with the precision of a surgeon rather than the chaos of a wrecking ball.
If you’ve ever felt like you’re fighting your tools instead of building with them, this is for you. Let’s talk about how to reclaim your codebase.
Creating a CLAUDE.md file is the difference between having a surgical assistant and a wrecking ball. In the Antigravity ecosystem, this file acts as the “Pre-flight Checklist” and “Rules of Engagement” that the agent reads before it executes a single command.
If you don’t provide this, the agent defaults to its “General Intelligence,” which usually favors aggressive refactoring. Here is how to structure a bulletproof CLAUDE.md to keep your project safe.
The Anatomy of a Perfect CLAUDE.md
A high-performance CLAUDE.md should be divided into four functional quadrants: Project Context, Guiding Principles, Technical Constraints, and The “Ask First” List.
1. Project Context (The “Where am I?”)
This section tells the agent exactly what this project is and what the tech stack looks like. This prevents it from suggesting libraries you don’t use (like suggesting Axios when you use Fetch).
# Project Context: TakeAsIstan / MOTOID
- **Purpose**: AI-powered classifieds and medical ID management.
- **Tech Stack**: Next.js (App Router), TypeScript, Tailwind CSS, Directus CMS.
- **Database**: PostgreSQL via Directus.
- **Critical Directories**:
- `src/app`: Routing and UI logic.
- `src/lib`: Core utilities and API clients.
- `src/hooks`: Custom React hooks for data fetching.
2. Guiding Principles (The “How we work”)
This section defines your coding philosophy. If you prefer functional components over classes, or if you hate unnecessary abstractions, state it here.
## Guiding Principles
- **Keep it Simple**: Prioritize readable code over clever "one-liners."
- **Atomic Components**: Build small, reusable UI components in `src/components/ui`.
- **Type Safety**: Everything must be strictly typed. Avoid `any` at all costs.
- **Consistency**: Match the existing naming conventions (e.g., camelCase for variables, PascalCase for components).
3. Technical Constraints (The “Brakes”)
This is the most important part for preventing project destruction. This section stops the agent from “optimizing” your config files or changing your deployment scripts.
## Technical Constraints
- **Framework Limits**: Only use Next.js App Router patterns. Do not use `pages/`.
- **Styling**: Tailwind only. No inline styles, no CSS Modules.
- **State Management**: Use React Context for UI state. Do not install Redux or Zustand without permission.
- **Performance**: Do not add heavy 3rd-party libraries for simple tasks. Try to use native Web APIs first.
4. The “Ask First” Protocol (The “Laws”)
This section is your safety net. It forces the agent to stop and get a “human-in-the-loop” approval before doing anything risky.
## The "Ask First" List
1. **Structural Changes**: If a task requires moving or renaming files, you MUST ask.
2. **Refactoring**: Do not refactor code outside the immediate scope of the task.
3. **Dependency Changes**: Ask before adding or updating any entry in `package.json`.
4. **Environment Variables**: Do not change `.env.example` or suggest new env vars without explaining why.
Full Example: Copy-Paste Template for Antigravity
Save this as CLAUDE.md in your root directory:
# Project: Antigravity Governance Guide
## 1. Context & Architecture
- **Framework**: Next.js 14+ (App Router).
- **Primary Language**: TypeScript.
- **Styling**: Tailwind CSS + ShadcnUI.
- **Backend**: Directus SDK / Supabase.
## 2. Coding Standards
- **Components**: Functional components with `export function` syntax.
- **Hooks**: Use custom hooks for all data fetching logic; keep components "thin."
- **Files**: One component per file. Filenames should match the component name.
- **Error Handling**: Use Try/Catch blocks in Server Actions and provide user-friendly feedback.
## 3. Strict Prohibitions (Preventing Destruction)
- **NO GLOBAL REFACTORS**: Stay within the file(s) I give you.
- **NO DELETIONS**: Do not delete utility functions just because they are "currently unused."
- **NO CONFIG CHANGES**: Do not touch `next.config.js`, `tailwind.config.ts`, or `tsconfig.json` unless explicitly told.
## 4. Agent Workflow
- **Plan First**: For any task affecting more than 2 files, provide a 3-step plan before writing code.
- **Verification**: After writing code, check the imports to ensure no circular dependencies were created.
- **Documentation**: Update existing JSDoc comments if logic changes, but do not add excessive comments to obvious code.
Why This Works for Antigravity
- Reduced Token Noise: By having a dedicated file, you don’t have to repeat your rules in every prompt. The agent “knows” these are the house rules.
- Logical Weight: High-level agents like Claude give immense weight to Markdown files in the root that look like “System Instructions.”
- Conflict Resolution: When the agent is deciding between “Should I clean this up?” and “Should I just fix the bug?”, the Strict Prohibitions section acts as the tie-breaker.
Expert Tip: If you find the agent still making a specific mistake (like constantly trying to use axios when you use fetch), add a specific line to your CLAUDE.md: “We use Fetch API, never Axios.” The file should be a living document that grows as you “train” your agent.
Do you have a specific architectural pattern in your project (like a certain way you handle medical data) that the agent keeps getting wrong?
