How to Train Your AI (agent)

How rules files shape your AI-driven workflow

Programming is undergoing a paradigm shift. AI-paired development isn’t a novelty. It’s becoming the new normal. And that shift demands new workflows. One of the most essential is the rules file: a plain-text document that tells your AI how to behave inside your environment. These aren’t nice-to-haves. In AI-native development environment (IDEs) like Cursor or Windsurf, they’re required infrastructure. So, what exactly is a rules file?

A rules file instructs an AI agent how to behave. For example, when you start a new chat with an agent like ChatGPT, it knows nothing about your workflow or the mode you're operating in. Rules files supply that missing context—guiding behavior with your experience and preferences to shape the output. Without these files, the output suffers. In IDEs, rules are typically markdown files (e.g. “general_rules.md”) sent with every request to shape the response.

At a high level, these files capture your preferences around things such as style conventions, architectural choices, and repeatable patterns. What follows are some basic examples to get you thinking.

The Personality

This is at the core of your rules files. It dictates how your AI agent should present itself and behave. A trivial example looks like:

You are a senior software engineer. You approach problem solving from the perspective of deconstruction—you break tasks down into manageable, atomic pieces. You look for simple solutions before conceding to complexity. As you present your suggested solutions, you outline your reasoning and thinking. You engage critically with problems and ensure your solutions are well-reasoned.

Instructions like this can affect how the AI reasons, whether it explains steps, or how assertive it is in making choices. For example, a personality set to “senior engineer who prefers clarity over cleverness” will often avoid terse one-liners in favor of clearer constructs. Depending on your experience, this can be tuned for more effective collaboration.

The Conformist

At the heart of every team, and developer, are conventions and styles that have developed over years. This file isn’t a preferences dump. It’s where hard-won conventions are captured. And it's the file that might see the most amount of churn. It should be actively maintained to ensure it's capturing the team's best practices. Without a file like this, you risk re-litigating the same choices with every code suggestion.

Do you prefer specific patterns in certain circumstances? Outline them here. Do you have patterns, say in testing, that are non-negotiable? Outline them here.

Here's an example:

* When starting a new project, always include the Ruby gem dotenv
* Use string interpolation instead of concatenation
* When creating a class, always stub out a spec file
* Prefer single quotes for strings unless interpolation is needed
* Unless otherwise requested, use the Ruby gem Faraday for HTTP requests
* Use factories (not fixtures) for test data setup
* Document all environment variables in the README or .env.example

The Architect

While the Conformist deals with code style and routine conventions, the Architect governs higher-level design, system behavior, preferences, and architectural principles. This file is especially useful when you have established opinions about how software should be structured, preventing drift and maintaining consistency. For example:

* Use pub/sub for inter-service communication unless strong consistency is required
* Default to simple structs or plain classes; avoid introducing complex base classes or inheritance without need
* For persistent data models, prefer composition over deep nesting
* When creating APIs, enforce idempotency for all POST endpoints unless explicitly marked as one-time actions
* For background jobs, include an exponential retry policy and failure alerting scaffold by default
* When adding a new feature, generate a feature flag scaffold to control rollout

Not every decision is black and white, but these rules can nudge the AI toward your defaults. They're especially useful when consistency matters more than innovation.

Parting Tips

Some advice for putting rules files to work:

• Keep your rules files modular, like outlined above, for easier maintenance

• Treat these files as living documents, update them anytime the AI falls short of your standards

• Consider versioning your rules files in a personal or team repo

  • They can easily be symlinked into new project directories

• Create purpose-built files (e.g. “reviewer.md” or “debugger.md”) for specialized workflows

• Rules files aren’t restricted to developers, they can be useful for project managers or other professionals (e.g. ChatGPT calls them “traits”)

• Add code examples, with instructions, to be explicit in your preferences

---

Rules files are already essential. They aren’t documentation, they aren’t optional, they’re working memory distilled from decades of collective experience driving the output of the agents your teams use. They’re how things are done.