I’ve been using AI coding agents for a while now. I mostly use GitHub Copilot, Cursor and Claude Code, but the same would apply to any other AI coding agent. My initial thinking was to keep repositories AI-free as possible and use AI as an assistant for my coding. This changed last year. At this moment I only write manually the core parts of code and contracts. Everything else is mostly AI generated. This effectively triggered a transition from human-first repositories to human-read-ai-write-first.

Here’s what I’m observing working best in my repos and teams.

Six Things That Actually Matter

1. Feedback Loop

This is the most important one. Your agent needs to know if what it’s doing is right or wrong.

  • Linting and Type checking - Immediate feedback on style and types. Agent can fix its own issues before going further.

  • Tests - Unit tests, integration tests. But also smoke tests - simple checks that verify the app actually runs.

  • Running the application - Agent should be able to start the app, hit endpoints, check UI. If something looks broken, it can see that.

  • CI/CD - Automated checks on every push. If tests fail, agent knows something is broken.

The key point: agent must have access to all of this. It’s not enough to have CI running somewhere. Agent needs to read CI status, see logs, understand what failed. Same with tests - agent should run them locally, not just hope CI catches issues later. If your agent can’t check CircleCI status or read test output, the feedback loop is broken.

The pattern: anything that gives automated feedback helps. If a human would catch an issue in review, try to automate that check so the agent catches it first.

2. Entry Points

Agent needs to know where to start. There’s a hierarchy that works:

  • README.md - Still the main entry point. What the repo does, how to run it, how to test it. This should work for humans AND agents.

  • AGENTS.md - Agent-specific instructions. This is becoming a standard de facto - over 20,000 repos on GitHub use it now. Put things here that a human would figure out but an agent might miss. Cloud environment setup, specific workflows, gotchas.

  • Tool-specific files - CLAUDE.md, .cursorrules, etc. If you use one tool primarily, you might have these. But I usually just make them reference AGENTS.md to avoid duplication.

Pro tip: keep AGENTS.md lean. It should give context and hints, not detailed step-by-step workflows. There are much more information in GitHub’s research.

3. Specifications

Some decisions can’t be figured out from code. Business rules, architectural choices, branding guidelines - this stuff lives in people’s heads or in Confluence pages that nobody reads.

I keep a specs/ folder with markdown files. Short documents about:

  • Architecture decisions
  • Domain concepts
  • Style guidelines
  • Integration requirements

Key rules:

  • Keep them short. If specs are too detailed, agent can’t distinguish spec from generated content.
  • Keep them current. Specs that say one thing while code does another are worse than no specs.
  • Update specs with PRs. When you change behavior, update the spec.
  • Keep short information on considered and discarded approaches to help the agent understand the reasoning behind decisions.
  • Make sure that specs are mentioned in AGENTS.md, and also updating specs is part of the pre PR checklist.

I periodically ask the agent to review recent commits and sync up specs. Works surprisingly well.

4. Progressive Disclosure

Here’s where it gets interesting. You don’t want to dump everything into AGENTS.md. That file would become massive and the agent would be overwhelmed.

The solution is progressive disclosure - show information only when needed.

Rules/Workflows - Most AI tools support some form of “rules” that load on demand. Cursor has .mdc files. Claude Code has skills. The idea is the same: brief description visible always, full content loads when relevant.

Example: you might have a rule for “how to create a PR in this repo”. The agent sees “PR creation guidelines” in the list, but only loads the full 50-line workflow when actually creating a PR.

5. Skills (Encapsulated Capabilities)

Rules are just text. But sometimes you need more. Here’s where Anthropic’s skills comes in.

Skills are like rules but they can include scripts and resources. Everything encapsulated together.

For instance I have a skill that checks CircleCI status. It includes:

  • Scripts to query the API
  • Instructions on how to interpret results
  • Common failure patterns and what they mean

Agent triggers the skill, runs the scripts, interprets the output. Fully self-contained.

Claude Code has native skill support. Other tools are catching up. But even if your tool doesn’t support skills natively, you can describe them in AGENTS.md and the agent will figure it out.

6. Testing Documentation

You won’t review every line of AI-generated code. You need the agent to self-verify.

Beyond unit tests, I keep human-readable test cases:

  • How to smoke test the main flows
  • What screens to check after UI changes
  • How to verify API changes work

This gives the agent a checklist. After making changes, it can run through verification steps before calling the task done.

At this moment running test cases is still unreliable, but I expect this to improve quickly.

What About Tool Fragmentation?

Yeah, it’s a mess. Different tools want different config files:

  • Copilot: .github/copilot-instructions.md, GitHub Copilot already supports AGENTS.md, so just adopt AGENTS.md
  • Claude: CLAUDE.md, I tend to have CLAUDE.md with just @AGENTS.md
  • Cursor: .cursorrules, Cursor already supports AGENTS.md

AGENTS.md is trying to unify this. Most tools support it now. My approach: use AGENTS.md as source of truth, make tool-specific files just reference it.

Minimum Viable AI-Ready Repo

If you’re starting from zero, prioritize:

  1. Working CI that runs tests and linting
  2. README.md with setup and test commands
  3. AGENTS.md with project-specific context
  4. Type checking if your language supports it

That’s 80% of the value. Everything else is optimization.

The Unexpected Insight

Someone said this and it stuck with me: “AGENTS.md’s greatest contribution isn’t standardizing AI configuration—it’s forcing developers to finally write decent documentation.”

True. Making your repo AI-ready is basically making it developer-ready. Clear entry points, automated verification, documented decisions. Things we should have been doing all along.

The AI just forces the issue.

Unexpected Insight