Rules files and context - teaching the agent your codebase

· Agentic coding demystified

So, you did your first agentic session. Congrats! The agent wrote code that compiles, runs, and technically does what you asked. But you looked at it and thought… “this is not how we do things here.”

The architecture is wrong. The naming is off. It puts files in places that make no sense for your project. It used some library you’ve never heard of when you’ve got a perfectly good utility that does the same thing. The code works, but it looks like a stranger wrote it. Which, to be fair, it is.

This is the single most common complaint I hear from people who try agentic coding for the first time: “It writes code that works but doesn’t match my project.” And the fix is simpler than you think.

Rules files: your project’s instruction manual

Most agent tools support some form of a “rules file” — a file that lives in your repo and tells the agent how your project works. Think of it as onboarding documentation, but for your AI pair programmer.

Different tools call them different things:

The name and format vary, but the concept is identical: a file in your repo that the agent reads before it starts working. It’s the “hey, before you write any code, here’s how we do things” brief.

And no, you don’t need to pick just one. If your team uses different tools, throw a few of these in your repo. They don’t conflict, and they’re just text files. Low cost, high impact.

What to put in them

Here’s where people either overthink or underthink this. You don’t need to write a 50-page architecture document. But you also can’t just write “make good code” and call it a day.

Here’s what actually matters:

Architecture pattern

This is the big one. If your project uses MVVM, say so. If you’re using TCA, say so. If you’ve got your own homebrewed architecture that you swear is better than everything else (we all have that friend), describe it.

## Architecture
We use MVVM across the app.
- Views are SwiftUI views that observe a ViewModel
- ViewModels are ObservableObject classes that handle business logic
- Models are plain structs in the Models/ folder
- Views never call services directly, always go through the ViewModel

Naming conventions

You’d be amazed how much this one matters. Agents love making up their own names, and they’re rarely the ones you’d choose.

## Naming
- ViewModels: `{Feature}ViewModel` (e.g., `SettingsViewModel`)
- Views: `{Feature}Screen` for full screens, `{Feature}View` for components
- Files match their primary type name
- Use camelCase for properties, PascalCase for types

File structure

Where do things go? The agent doesn’t inherently know that your ViewModels go in Sources/Features/{Feature}/ViewModels/ and not just floating around in the root.

## File structure
Each feature has its own folder under Sources/Features/:
- Sources/Features/{Feature}/Views/
- Sources/Features/{Feature}/ViewModels/
- Sources/Features/{Feature}/Models/
Tests mirror the source structure under Tests/Features/

Preferred libraries and patterns

If you’ve got a design system, mention it. If you use specific libraries for networking, storage, or whatever, list them. This prevents the agent from importing random third-party dependencies.

## Libraries & patterns
- Networking: Use our APIClient (Sources/Networking/APIClient.swift), NOT URLSession directly
- UI components: Use components from our DesignSystem module
- Navigation: Use the Router pattern (see Sources/Navigation/Router.swift)
- Async: Prefer async/await over Combine for new code

Beyond rules files: context in your prompts

The rules file is your baseline. It covers the general stuff that applies to every task. But for specific tasks, you’ll want to give the agent more context directly in your prompt.

Here’s the difference:

Rules file (general): “We use MVVM, files go in Features/ folders, use our DesignSystem module.”

Prompt context (specific): “Add a settings screen. Look at how ProfileScreen is built — follow the same pattern. The toggles should use DesignSystem.Toggle, and navigation should go through the Router.”

See the difference? The rules file sets the stage. The prompt points at specific examples. Together, they give the agent everything it needs to write code that actually fits your project.

Some tips for giving good context:

The payoff

Let me paint a picture.

Without rules or context: You ask the agent to add a settings screen. It creates a single massive ViewController with inline layout code, imports a random settings library from GitHub, puts everything in a folder called “Misc”, and names the class “SettingsVC.” It works, but you want to cry.

With rules and context: You ask the agent to add a settings screen. It creates a SettingsScreen view that observes a SettingsViewModel, uses your DesignSystem.Toggle for switches, follows your Router for navigation, puts files in Sources/Features/Settings/, and the code looks like it was written by someone who’s been on your team for months.

Same agent. Same model. Same intelligence. The only difference is you told it how your project works. That’s it. That’s the whole trick.

A starter template

Here’s a rules file you can steal, adapt, and throw in your repo today. It’s opinionated — change it to match your project, not mine.

# Project Rules

## Architecture
- We use [MVVM/MVI/TCA/whatever you use]
- [Brief description of the data flow]
- [Any other architectural constraints]

## Naming Conventions
- Views: `{Feature}Screen` for full screens, `{Feature}View` for reusable components
- ViewModels: `{Feature}ViewModel`
- Models: plain descriptive name (e.g., `UserProfile`, `Settings`)
- Files match their primary type name

## File Structure
- Features live in `Sources/Features/{FeatureName}/`
- Each feature has Views/, ViewModels/, and Models/ subfolders
- Tests mirror source structure under Tests/

## Dependencies & Libraries
- Networking: [your networking setup]
- UI: [your design system or UI library]
- Navigation: [your navigation approach]
- Storage: [your persistence approach]

## Code Style
- [Async approach: async/await, Combine, RxSwift, etc.]
- [Error handling approach]
- [Any specific linting rules or formatters]

## Things to Avoid
- Don't add new third-party dependencies without asking
- Don't use [deprecated pattern/library] - use [preferred alternative] instead
- Don't put business logic in Views

Copy it, fill in the brackets, drop it in your repo root, and you’re 80% of the way there. You can refine it over time as you notice patterns the agent keeps getting wrong.

Takeaways

Next time, we’ll look at managing your context windows, through actual examples and usages!. Stay tuned.