@agent — Code Annotations for AI Agents

AI agents are now a routine part of how code gets read, refactored, and extended. They are a fourth audience alongside humans, compilers, and IDEs — but unlike the other three, they have no established annotation vocabulary written to them.

The repository https://github.com/codebasedlearning/agent-annotations-spec.git proposes one.

The problem in one paragraph

When an agent opens a file in a multi-repo codebase, it sees the file. It does not automatically see that an enum in the Python backend must stay in sync with its counterpart in the Kotlin mobile client, that a client-side validation function is not the authoritative enforcement point, or that a regex pattern in one module implicitly constrains a constructor in another. A human architect carries that knowledge as hard-won context. An agent reconstructs it from naming and structure — or gets it wrong. And it starts over from scratch in every new session.

@agent annotations are a convention for making that knowledge explicit, inline, where the code lives.

What it looks like

Two enums in two languages, two repositories, zero shared interface — linked by a single ident:

# acme.hub / src / errors.py

# @agent sync "error-codes"  Kept in sync manually — no codegen
class ErrorCode(enum.Enum):
    NOT_FOUND    = "not_found"
    FORBIDDEN    = "forbidden"
    CONFLICT     = "conflict"

// acme.clients / api / ErrorCode.kt

// @agent sync "error-codes"
enum class NameErrors(val value: String) {
    NOT_FOUND("not_found"),
    FORBIDDEN("forbidden"),
    CONFLICT("conflict"),
}

A reader — human or agent — encountering either file immediately knows the other exists and knows to keep the content in sync. No URI, no build step, no schema. The ident "error-codes" is the link.

A more consequential example — the difference between a gate and a hint:

# @agent enforced-by "email-uniqueness"  UI feedback only — server is the real gate; this check can be bypassed
def check_email_available(email: str) -> bool: ...

# @agent enforces "email-uniqueness"  Authoritative — client check is UX only, never remove this
async def create_user(email: str, conn: asyncpg.Connection) -> User: ...

An agent that doesn't know the distinction might remove the server check as redundant. That's a security bug, not a style issue.

Format

@agent [command] [ident] [comment]

Place in any line comment or docstring, adjacent to the symbol it describes. Works in every language that supports comments. No tooling required — grep -r "@agent" . is enough to find all annotations across a codebase.

Commands include sync, defines, defined-by, related-to, enforces, enforced-by, assumes, guarantees, affects, deprecated, and keep. A bare @agent with no command is a valid free-form note.

Full specification can be found here https://github.com/codebasedlearning/agent-annotations-spec.git

Status

Early draft. The command vocabulary is stable enough to use; the ident convention and agentref:// URI scheme are more provisional. Feedback via issues is welcome — especially reports from real codebases on what works, what is awkward, and what is missing.

The most useful thing anyone can do right now is the five-minute test: take a file with non-obvious cross-project relationships, ask an agent what would break if you changed it, add @agent annotations, and ask again. The delta is the evidence.

I'd love to hear your feedback.