Context Engineering: How to Teach AI About Your Codebase

The Problem with "Out of the Box" AI

Try asking an AI coding assistant to write a feature in a new project. The result might be technically correct, but often:

• Uses different patterns than what's existing in the codebase
• Ignores naming conventions the team agreed upon
• Is unaware of already available libraries or helpers
• Makes architectural decisions that conflict with previous ones

This isn't the AI's fault. AI doesn't know what it isn't told.

Context engineering is the discipline of **giving AI the right information** about your project — so the generated output is consistent, relevant, and actually useful.

What Should Be in Context

**1. Architectural Overview**

A short document (500-1000 words) explaining:

• The tech stack and why it was chosen
• Folder structure and what goes where
• Main patterns used (e.g., repository pattern for data access, or custom hooks for state management)
• External services and integrations

**2. Coding Conventions**

Specific things the team agreed on:

• Naming conventions (PascalCase for components, camelCase for functions, etc.)
• File structure within a feature/module
• How to handle errors and edge cases
• Patterns for async operations

**3. Decision Log**

This is often forgotten: document *why* a decision was made, not just *what* the decision was.

"We use Zustand instead of Redux because this project is small enough and Redux is too verbose for our use case" — this kind of information prevents AI (and new developers) from making conflicting decisions.

**4. Current Task Context**

In addition to permanent project context, provide specific context for each task:

• Relevant files and functions
• Expected behavior
• Constraints and edge cases
• What was already tried and why it didn't work

Rules Files: Persistent Context

Some AI coding tools support "rules files" — configuration files that are always loaded into every session. At Idin Studio, we maintain one rules file per project containing the core of all the context above.

The structure we use:

```

# Project: [project name]

Stack

...

Architecture

...

Conventions

...

Important Decisions

...

What to Avoid

...

```

This file lives in the repository and is updated whenever there's a new architectural decision or convention change. New developers joining the project immediately have a solid understanding — and AI working on that project is always in the right context.

Context Hierarchy

In practice, we use three levels of context:

1. **Global rules**: Conventions that apply to all projects (commit message format, basic security practices)

2. **Project rules**: Specific to this project (stack, architecture, local conventions)

3. **Task context**: Specific to the task currently being worked on

The more specific and relevant the context provided, the better the AI output.

A Worthwhile Investment

Creating and maintaining this context documentation takes time — but the investment pays off:

• AI generates more consistent code and needs fewer revisions
• New developers onboard faster
• Technical decisions are stored in an accessible place

In the era of agentic coding, context engineering isn't a nice-to-have. It's the foundation that makes everything else work well.