This is an instructions file. It lives in your repository root. Your AI coding assistant reads it before touching your code.

You can call it CLAUDE.md or AGENTS.md or INSTRUCTIONS.md or whatever your tooling expects. The name doesn’t matter. What matters is that you’re encoding expectations that would otherwise live in your head.

What follows is a starting point. Steal it. Modify it. Delete the parts that don’t apply. Add the parts that do.

# AI Coding Instructions

## Context Awareness

Before writing code, establish your working context:

- What module or layer am I working in?
- What are this module's dependencies?
- What interfaces does this module expose?
- What interfaces can this module consume?

Do not reach outside your working context without acknowledging the boundary crossing. If you need functionality from another module, say so. Don't just import it and hope for the best.

If you're unsure what the boundaries are, ask. "I need to call into the authentication module from here. Is that an expected dependency, or am I crossing a boundary that shouldn't be crossed?"

## Before You Create, Search

Before creating a new utility, helper, or abstraction:

1. Search for existing implementations
2. Check if something similar exists under a different name
3. Ask: "Am I about to write something that already exists in slightly different form?"

If you find something similar, prefer extending or reusing it over creating a new one. Duplication is sometimes fine. Accidental duplication rarely is.

## Modification Requires Justification

When you want to change existing code (especially shared code, interfaces, or utilities):

1. Explain why the change is necessary
2. Identify who else depends on what you're changing
3. Consider whether extension would work instead of modification
4. Surface the decision before making it

Here's the kind of surfacing that works well:

"I need user data with orders. The current interface has `GetUser()` and `GetOrders()` separately. I could:
1. Add `GetUserWithOrders()` (quick, but there are already 3 similar methods)
2. Compose the existing methods at the call site
3. Refactor to a more flexible query pattern

Which approach fits the codebase better?"

## Impact Awareness

When modifying shared code:

- Identify all callers and implementations
- Verify your changes work for existing uses
- Update all affected code in the same change
- Do not leave the codebase inconsistent

If the impact is larger than expected, stop and surface it. "This change affects 12 files across 4 modules. Should I proceed, or should we discuss the scope?"

## Depend on Interfaces

Prefer depending on abstractions over concrete implementations. If you're reaching for a concrete class when an interface exists, pause. Ask yourself why.

If you can't implement a feature through available interfaces, that's information worth surfacing. Maybe the interfaces need to evolve. Maybe the feature belongs somewhere else. Maybe the request doesn't fit the architecture.

## When Stuck, Stop

If you hit a wall:

- Don't route around the architecture
- Don't create workarounds that bypass existing patterns
- Don't modify unrelated code to make your path easier

Instead, stop and explain:
- What you're trying to accomplish
- What's blocking you
- What options you see

Let the human make the architectural call. That's the division of labor.

## Considered Over Expedient

Every change should answer:

- Where does this belong?
- How does it relate to what exists?
- What's the impact of adding it?
- Is this the right solution, or just the fastest one?

Prefer changes that *belong* over changes that merely *work*.

Using This File

This isn’t a rulebook. It’s a set of prompts that force pause points.

The goal is an AI assistant that understands code exists in context. One that pauses at boundaries, surfaces decisions, and asks before reaching.

Modify these instructions based on what keeps going wrong. If your AI keeps creating duplicate utilities, strengthen the “search before creating” section. If it keeps modifying shared interfaces without thinking, add examples of what good looks like.

The best instructions file is the one that prevents the mistakes you keep making.