DEV Community

Cover image for When Two AI Agents Drift Apart
mortylen
mortylen

Posted on Originally published at mortylen.hashnode.dev

When Two AI Agents Drift Apart

How to keep AGENTS.md, CLAUDE.md and copilot-instructions.md in sync

Do you use more than one AI coding tool in a single project? Or do several developers work on the project, each with a different AI agent? Then you probably have several instruction files as well: AGENTS.md, CLAUDE.md, .github/copilot-instructions.md and more.

Most of the time they say the same thing: which conventions apply in the project, what the AI agent may and may not do, which architecture the project uses and which decisions have been made.

At first the files are identical, because we copy the same text into each tool's file. But over time, changes start to arrive. You update one file and forget the other, or a colleague changes the instructions only for their own tool. And suddenly two agents work on the same project, each following different rules.

I am the author of an open-source tool called AIContext, which tries to solve this problem. The goal of this article, however, is not to convince you to use it. I want to show what the problem looks like, when a much simpler solution is enough, and when a tool like this might be useful.

What drifting files look like

The following example is illustrative, not an experience from a real project. Imagine a project where one developer uses a tool that reads AGENTS.md and another uses GitHub Copilot. Both files contain the same two documentation rules:

- Use project-relative paths in documentation examples.
- Document the expected output for each command example.
Enter fullscreen mode Exit fullscreen mode

The team then decides that command examples should also document the exit code. Someone updates AGENTS.md:

 - Use project-relative paths in documentation examples.
-- Document the expected output for each command example.
+- Document the expected output and exit code for each command example.
Enter fullscreen mode Exit fullscreen mode

Nobody updates .github/copilot-instructions.md. No error, no warning. Nobody notices the difference until they stumble on it by chance: Copilot suggests documentation without the exit code, and nobody understands why.

When a simpler solution is enough

Right from the start: if one short hand-written file is enough for you, keep it. If you use a single tool, the problem does not arise at all.

With two or three files, one source file and a way to copy it is often enough (a script, a make target or a git hook). In CI, you can simply compare the copies with diff. A solution like this takes ten minutes. If it covers your needs, you need nothing more.

Also check what the tools themselves offer. Some read several files at once (for example, Copilot reads AGENTS.md as well in some modes), so sometimes maintaining a single file is enough.

It starts to get more complicated when:

  • the tools need different formats: each has its own header and its own way of defining which files a rule applies to,
  • you want to review changes to instructions in pull requests and verify in CI that all files match the source,
  • the project grows and you do not want to send the agent every rule with every question,
  • several people edit the instructions and copying by hand stops being reliable.

These are exactly the cases I created AIContext for.

How AIContext works

AIContext keeps the whole source in a single .aicontext/ directory as plain Markdown and JSON, and generates files for the tools you choose from it. It is a simple CLI tool. Everything runs locally, with no AI account and no model calls.

Installation: download a standalone binary from the release page (it does not need .NET), or, if you have the .NET SDK, install it as a tool:

dotnet tool install --global AIContext.CLI
Enter fullscreen mode Exit fullscreen mode

You can verify that it works with aicontext --version:

aicontext 0.7.0
Specification version: 0.1.0
Enter fullscreen mode Exit fullscreen mode

1. The source

In the project root, run aicontext init --name my-project. This creates a .aicontext/ directory with three files:

  • README.md is a short project description that appears in all outputs,
  • constraints.md contains the rules:
  # Documentation rules

  - Use project-relative paths in documentation examples.
  - Document the expected output for each command example.
Enter fullscreen mode Exit fullscreen mode
  • context.json defines which tools the files are generated for:
  {
    "$schema": "https://aicontext.dev/schema/v1/context.schema.json",
    "specVersion": "0.1.0",
    "project": { "name": "aicontext-demo" },
    "exports": { "targets": ["agents", "copilot"], "layout": "single" }
  }
Enter fullscreen mode Exit fullscreen mode

2. Validation and export

aicontext validate
  AIContext validation passed (Core profile).

aicontext export --target all
  Created (agents): AGENTS.md
  Created (copilot): .github\copilot-instructions.md
  Export completed (2 changed, 0 unchanged).

aicontext export --target all --check
  Export is up to date.
Enter fullscreen mode Exit fullscreen mode

validate checks the structure and obvious placeholder text. In a small example like this it also prints two expected warnings: the recommended files architecture.md and decisions.md are missing. The word all here means only the two targets from context.json, not all supported tools.

3. Changing a rule

Now I change one rule in the source (constraints.md), adding "and exit code", and run the check:

aicontext export --target all --check
  Export is out of date (2 file(s)). Run 'aicontext export' to update.
Enter fullscreen mode Exit fullscreen mode

--check writes nothing; it only reports the difference and exits with code 1, so it fails in CI. Only the aicontext export --target all command updates both files at once, and the change is the same in both:

 - Use project-relative paths in documentation examples.
-- Document the expected output for each command example.
+- Document the expected output and exit code for each command example.
Enter fullscreen mode Exit fullscreen mode

You edited a single source and the tool updated both outputs. Running the export again without changes ends with Export completed (0 changed, 2 unchanged). The output is deterministic (no timestamps, always LF line endings), so an unchanged source produces no diff in git.

Rules for working with generated files

  • Do not edit generated files by hand. Each has the header Auto-generated by aicontext export and is overwritten on the next export. Always edit .aicontext/.
  • Both groups of files belong in git: .aicontext/ and the generated files, because the tools read them directly from the repository.
  • The tool will not accidentally overwrite your hand-written files. It only overwrites files with the Auto-generated by aicontext export header. If your project already has its own AGENTS.md, the export reports a conflict and writes nothing (not even the other files) until you explicitly use --force. To move to AIContext, proceed like this:
    1. aicontext init lists the hand-written instruction files it found.
    2. You move their content into .aicontext/.
    3. aicontext export --dry-run shows what would change, without writing anything.
    4. Only then do you run the export with --force. And if you change your mind, Git lets you restore the original state.

Checks in CI

The export alone is not enough if someone forgets to run it. That is why there are two independent checks:

  • aicontext validate --strict catches unfinished source. A TODO: … line is only a warning in regular validation, but in strict mode the command fails.
  • aicontext export --target all --check catches generated files that do not match the source. This happens when someone changes .aicontext/ and forgets to run the export, or when someone edits a generated file by hand.

A simple workflow for GitHub Actions (no .NET, it downloads a standalone binary):

name: Check AIContext exports
on: [pull_request]
permissions:
  contents: read
jobs:
  check-context:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - run: |
          curl -fsSL https://github.com/aicontext-dev/aicontext/releases/latest/download/aicontext-linux-x64.tar.gz | tar -xz -C /usr/local/bin aicontext
      - run: aicontext validate --strict
      - run: aicontext export --target all --check
Enter fullscreen mode Exit fullscreen mode

CI should only check the files, not fix them. If it generated them before checking, a missing export would never be detected. That is why the workflow generates nothing and writes nothing to the repository. If the check fails, the author runs the export locally and pushes the change again. In a real project, I recommend pinning a specific version instead of latest (an example is in demo 03).

You can also catch the mistake earlier with a pre-commit git hook:

#!/bin/sh
aicontext validate --strict && aicontext export --target all --check
Enter fullscreen mode Exit fullscreen mode

Larger projects: scoped rules

When the context is large, not every rule needs to be sent to the agent with every question. You do not need the documentation rules when editing the database layer. That is why in AIContext you can bind a rule to specific files. Just save it in .aicontext/rules/ and state in the header which paths it applies to:

---
description: "Guidance for documentation pages"
paths: ["docs/**"]
---

- Use project-relative paths in documentation examples.
Enter fullscreen mode Exit fullscreen mode

After you enable "layout": "split" in context.json, AIContext generates the rule in the tool's native form. For Copilot, for example, it creates the file .github/instructions/aicontext-docs.instructions.md with applyTo: "docs/**". Tools that do not support rule scoping (for example AGENTS.md) get the rule in the main file, together with a text note saying which files it applies to.

If a tool cannot express the scope precisely, the export is refused rather than letting the rule silently apply to the whole project. Before anything is written, you can preview the changes with aicontext export --dry-run. A step-by-step guide is in demo 02.

What AIContext does not solve

  • AIContext verifies files, not agent behavior. I do not claim that any particular tool will load or follow a rule.
  • Generating a file does not mean the tool will read it. Aider, for example, does not load CONVENTIONS.md on its own (you need aider --read CONVENTIONS.md or a setting in .aider.conf.yml), and VS Code has its own settings for Copilot.
  • Some tools read several files at once, so exporting to multiple targets can duplicate the context. The AGENTS.md and Copilot pair in this article is an example of file synchronization, not a universal recommendation. aicontext status estimates such overlaps, but it is an estimate, not a measurement of a live session.
  • AIContext is at version 0.x, so formats and behavior may still change.
  • Secret detection is a heuristic and does not replace a dedicated scanner.

AIContext is also not for everyone. Do not use it if:

  • you use one tool and one short file works for you,
  • you expect the tool to write the content for you (it only checks structure and obvious placeholder text),
  • you want to enforce what the AI does (context is a recommendation, not a policy).

Try it and let me know

If you have at least two files with the same instructions in your project, try the small demo in an empty folder. All you need is a standalone program, with no Git, no .NET SDK and no AI account. Then let me know whether the problem I describe is real for you too. The answer "a hand-written file is enough for me" is perfectly fine and very useful.

The cover image for this article was generated using AI.
AI tools also assisted me with editing the article’s style and grammar.

Top comments (0)