Stop Fighting Your AI Pair Programmer: Why Rule Files Actually Work (And How to Use Them Right)

Last month, I watched Claude generate a completely wrong folder structure for a React component I'd asked it to scaffold. Not technically wrong—it compiled fine—but wrong for our project. It didn't know about our feature-based colocation pattern. It didn't know we validate everything with Zod at the API boundary. It just applied some generic React best practices and called it a day.

That's when I realized I'd been approaching AI code generation all wrong. I wasn't giving the agent enough context about what "correct" looked like in my specific codebase. I was essentially asking a translator to work without a dictionary, then getting frustrated when the translation felt off.

The solution turned out to be almost laughably simple: a .md file at the project root that says "here's how we do things here." Not fancy. Not complicated. Just explicit rules that the agent reads before every session.

The Real Problem AI Agents Solve (And Don't)

Here's what I've learned from shipping production React with TypeScript and increasingly relying on AI agents: these tools are phenomenal at pattern recognition, but they're terrible at assumptions. They don't know your project's philosophy. They don't know why you chose Zustand over Redux, or why you banned React.FC in your codebase, or that you have a specific folder structure you're protective of.

Every time you correct an agent's output, you're essentially fighting against their training data, which represents thousands of codebases' conventions—most of which aren't yours. Without explicit rules, the agent makes a roll of the dice, and you spend time reviewing code that should've been right the first time.

A rule file—whether it's CLAUDE.md for Claude Code, .cursorrules for Cursor, or AGENTS.md for CLI tools—is just documentation that gets read every single session. It's not magic. It's not going to make bad code suddenly good. But it does remove the guessing game.

How to Structure This (And Not Waste Your Time)

The approach in the original article is pragmatic: different agents, different files. CLAUDE.md for your main context, CURSORRULES for editor-specific completion hints, AGENTS.md for CLI tasks. If you're using multiple agents (and let's be honest, most of us are now), one master file with includes is cleaner than maintaining three separate rule books.

I've been experimenting with this in my own Vite + React + TypeScript stack, and the sections that matter most are boring but critical:

• Component structure rules (where things live, how props are typed, naming conventions)
• Type safety constraints (Zod schemas, no unsafe casts, what validation lives where)
• Testing philosophy (which layers you actually test, which you don't, why)
• Safety guardrails (what the agent should never touch without asking)

The last one is underrated. "Don't modify .env files," "Ask before deleting anything," "Propose dependency changes, don't install them"—these sound obvious until you're three commits deep and realize Claude silently removed a utility function it thought was dead code.

What I'd Do Differently

I agree with the article's core premise: rule files work. But I'd push back slightly on one point—the article suggests growing your rules organically, adding one line each time the agent messes up. That's practical, but I've found that intentional upfront thinking pays off.

Before you start feeding tasks to an agent, spend an hour documenting your actual conventions. Not the aspirational ones. The ones you actually follow. Then let the agent operate within that frame.

Also, I'd be more aggressive about positive framing. "Use function declarations instead of React.FC" is clearer than "React.FC is deprecated." Agents parse positive instructions better than negations.

Here's what my current setup looks like:

## Component Patterns
- All components in `src/features/<domain>/` use colocated structure
- Export components as default, utils/hooks as named exports
- Prop types defined inline in the component file
- Use standard function declarations: `function ComponentName(props: Props) { ... }`

## Type Safety Layer
- All API responses validated through Zod schemas in `src/api/schemas/`
- No `as unknown as T` casts under any circumstances
- If a type doesn't match the schema, the schema is wrong, not the type

## What Not to Touch
- Do not modify, create, or read .env files
- Always ask before deleting any existing file
- Suggest new dependencies; never run `npm install`

Clear. Specific. Actionable.

The Real Test: Does This Scale?

Here's what I want to know: does this actually save time in practice? I think it does, but maybe not how you'd expect. It's not that the agent generates perfect code on the first try. It's that you spend less time in code review correcting style and structure decisions, which means more time reviewing logic and intent.

That's a win, even if it's not the magical productivity multiplier some AI evangelists promise.

Next Steps

If you're working with AI agents today, spend this week documenting three things: your folder structure, your type safety rules, and your safety constraints. Commit them. See what changes in your code review process over the next sprint.

And if you find that agents are generating stuff that's technically correct but doesn't fit your project's grain? That's not the agent failing. That's you not giving it enough information.

Source: This post was inspired by "2026年版・ReactエージェントへのCLAUDE.md実践ガイド" by Dev.to. Read the original article