The 2 AM Incident: When Your AI Agent Goes Rogue
It’s 2:14 AM, and my terminal is scrolling faster than I can read. I asked Claude Code to “fix the validation logic in the login controller,” but it’s currently refactoring the entire database schema and has already nuked 12 .env.example files. It flagged them as “redundant” and decided they didn’t belong in the repo.
If you’ve started using Anthropic’s new CLI tool, Claude Code, you’ve likely felt that mix of awe and pure terror. It is incredibly fast. However, without a leash, it acts like a junior dev who drank six espressos and decided to rewrite the company’s legacy codebase on their first day.
After cleaning up that specific mess, I realized the problem wasn’t the AI. I hadn’t given it a map. That map lives in the .claude/ directory. If you don’t define this directory, you are letting an agent run wild in your production repository with zero knowledge of your team’s standards.
Why Claude Code Hallucinates Your Project Structure
Think of it this way: when you launch claude in your terminal, it’s essentially a high-speed intern walking into a dark room. It performs an initial scan of your file tree and reads package.json to guess how you work.
Most Claude Code failures stem from three specific gaps:
- Context Deficit: It doesn’t know you prefer functional components over classes or that you use specific architectural patterns like Clean Architecture.
- Boundary Issues: It tries to “optimize” third-party library code in
node_modulesor messes with build artifacts in/dist. - Permission Ambiguity: It isn’t sure if it’s allowed to run destructive commands like
rm -rfordocker-compose downwithout asking first.
Without a structured configuration, the agent defaults to its general training data. This data is often 180 degrees away from your project’s specific requirements.
Three Ways to Control the Agent
Developers usually try to handle Claude Code’s behavior in one of three ways. Two of them usually fail when things get complex.
1. The “Manual Prompt” Method
You try to explain your rules in every single prompt: “Fix the bug but don’t change the CSS and use Tab indentation.” This is exhausting. It consumes roughly 200–500 extra tokens per turn, and the agent eventually forgets the instructions as the conversation history grows.
2. Global Configuration
You set global aliases or environment variables on your machine. This works for you, but the moment a teammate clones the repo, the consistency breaks. Your AI assistant will behave differently on every laptop in the office.
3. The .claude/ Directory (The Pro Approach)
By creating a .claude/ folder at the root of your project, you establish a permanent “Source of Truth.” This directory stays in your Git history. Every developer—and the AI itself—follows the exact same rules. I have applied this in production microservices, and it cut down “hallucinated refactors” by nearly 90%.
The Ideal .claude/ Structure
To keep your project clean and your AI agent sane, you need a specific set of files. Here is the structure I recommend for any serious TypeScript or Python project.
my-project/
├── .claude/
│ ├── config.json
│ ├── custom_instructions.md
│ └── project_context.md
├── src/
└── ...1. The config.json file
This file dictates the technical behavior of the CLI. It defines which tools the agent can touch. Here is a baseline configuration for a safe environment:
{
"auto_execute_commands": false,
"allowed_tools": ["read_file", "write_file", "list_files", "grep_search"],
"theme": "dark",
"model": "claude-3-7-sonnet-latest"
}Setting auto_execute_commands to false is my mandatory sanity check. It forces Claude to ask for permission before running any command that could wipe a database or push to a protected branch.
2. custom_instructions.md (The Rulebook)
This is the most critical file. Claude Code automatically looks for instructions here to determine its coding style. Don’t be polite; be aggressive with your requirements.
# Project Coding Standards
- Use TypeScript for all new files. No `any` types allowed.
- We use Tailwind CSS for styling. Do not create .css files.
- Use `pnpm` instead of `npm`. Never run `npm install`.
- When fixing bugs, always write a Vitest test case first.
- NEVER modify files in the `/legacy` folder.3. project_context.md (The Map)
AI models often struggle with large-scale architecture. They see individual files but miss the “Big Picture.” Use this file to explain how the parts of your project fit together. This saves thousands of tokens because Claude doesn’t have to “search” for the architecture.
# Project Context
This is a Next.js 14 app using the App Router.
## Key Directories:
- `/src/lib/api`: Contains all backend fetch wrappers.
- `/src/store`: Managed via Zustand for global state.
## Architecture Notes:
We use a hexagonal architecture. Keep business logic in `/src/core`
and framework-specific code in `/src/infrastructure`.Adding Safeguards with .claudeignore
Just like .gitignore, you must tell Claude what it cannot see. If you have 500MB log files or sensitive credentials, don’t let Claude scan them. It wastes money and creates security risks.
While Claude Code respects your standard .gitignore, I recommend being explicit. If you have a /temp_data folder that isn’t ignored by Git but shouldn’t be read by the AI, add it to your custom_instructions.md or a dedicated .claudeignore file if your version of the CLI supports it.
Workflow: From Babysitting to Supervising
Once your .claude/ directory is live, your daily workflow shifts. You stop correcting basic mistakes and start managing outcomes.
- Initialize: Run
claude. The agent reads yourcustom_instructions.mdimmediately. - Tasking: Give a high-level command: “Add a new user profile page.”
- Execution: Claude checks
project_context.md, sees you use the App Router, and selects the right directory without asking. - Review: Since
auto_execute_commandsis off, you review the plan before it touches your disk.
Final Thoughts
Setting up the .claude/ directory takes about 10 minutes. It saves hours of debugging AI-generated hallucinations later. This setup moves the “intelligence” from a generic cloud model to a specialized assistant that actually understands your codebase.
Commit your .claude/ directory today. Your teammates—and your future self at 2 AM—will thank you when the agent follows the rules instead of reinventing the wheel during a production hotfix.
