@agent — Code Annotations for AI Agents

A draft @agent annotation spec proposes inline comments to help AI coding tools understand code relationships and intent.

The annotations can mark synchronized enums, authoritative validation, and other cross-file or cross-language constraints.

By making invariants machine-readable, the spec aims to reduce refactor mistakes and security bugs in agent-assisted code changes.

The proposal is early-stage, but it could give AI agents the context they often miss in large codebases.