A comprehensive coding style and operational protocol for AI agents. This repository contains the AGENTS protocol — a set of mandatory rules, best practices, and operational guidelines that AI agents must follow when writing code in any language.
The AGENTS protocol is designed to produce code that is maintainable, secure, and reliable. It is written in the style of the Linux kernel coding style: concise, direct, and uncompromising about quality. Every line of code must have a reason. Every error must have a message. Every failure must be loud, immediate, and obvious.
The protocol is organized into a core document and language-specific satellite files. The core document establishes universal principles that apply across all languages and domains. The satellite files provide language-specific guidance, including required linters, idiomatic patterns, and common pitfalls to avoid.
Because models are mechanical, not moral.
Most production LLMs today are Mixture-of-Experts (MoE) or hybrids with MoE blocks. There are no mystical "serious experts" inside. There is only routing, matrices, and probability mass.
A token goes through the model layer by layer. In MoE layers, a router computes scores and sends that token to top-k experts. Each expert is just a parameterized function (usually FFN weights) specialized by training dynamics, not by human-readable job titles.
No expert is labeled "strict", "careful", or "dramatic". But different phrasing shifts hidden states, and hidden states change routing decisions.
That is the first mechanism.
The second mechanism is attention with K/V cache. Earlier tokens write keys and values; later tokens read them repeatedly. If instructions are weak, they become weak anchors. If instructions are explicit, categorical, and unambiguous, they remain strong anchors across subsequent generation steps.
In practical serving stacks, prefix/prompt caching is also common, so stable instruction patterns matter operationally, not philosophically.
So yes, wording is deliberate.
- Strong language reduces ambiguity.
- Reduced ambiguity stabilizes routing behavior.
- Stable routing and strong anchors improve instruction adherence.
- Better adherence means fewer silent failures and less cleanup by humans.
This is not theater. This is control of failure modes using the tools language gives.
The main document (AGENTS/AGENTS.md) contains ten foundational sections:
- The Prime Directive: Don't Know — Don't Do — Unwritten code is better than badly written code. If you do not understand the requirement, stop and ask.
- The Operator's Time Is Finite — Act Like It — Plan the entire task, batch your work, and minimize round-trips with the operator.
- Operational Workflow: Plan, Confirm, Execute, Report — A disciplined workflow that ensures every task is thought through, approved, and completed systematically.
- Fast Fail and Hard Fail — Detect errors early and crash with clear messages. Silent failures are infinitely worse than crashes.
- Error Messages Must Be Useful — Every error message must answer what happened, where it happened, and what the actual vs expected value was.
- Linting: No Exceptions, No Suppressions — If a linter exists for the language, code must pass it cleanly. Suppressions are not acceptable.
- Common Agent Mistakes and Delusions — A catalog of typical errors agents make, including context drift and over-engineering.
- The Runpoint Protocol — How to document incomplete work when execution is interrupted.
- The PLAN.md Contract — How to write atomic, specific plans before touching any code.
- Message to a Reviewing Agent — A template for passing context when delegating review to another agent.
Language-specific and topic-specific satellite files extend the core protocol with detailed guidance:
- Topic-specific: Secrets & Credentials, Git Discipline, Docker & Containers, SQL & Databases
- Language-specific: Python, C, C++, Rust, Java, Kotlin, Go, C# / .NET, Swift, JavaScript / TypeScript, CSS / SCSS, Shell Scripts (Bash/Zsh)
- Testing: General principles, testing pyramid (white/grey/black box), and concrete examples
Each satellite file includes:
- Minimum required linters and installation instructions
- Best practices and idiomatic usage
- Common mistakes and pitfalls
- Language-specific operational patterns
Every function must have a single responsibility. If you need the word "and" to describe what it does, it is doing too much. Code should be like WireGuard — minimal, correct, and exceptionally well-executed.
Errors must be detected at the earliest possible moment and the program must crash immediately with a clear message. Programs that silently produce wrong results are infinitely worse than programs that crash with clear errors.
An error message exists to tell the operator what went wrong so they can fix it. Every error message must answer what happened, where it happened, and what the actual vs expected value was.
If a linter exists for the language, it must be installed and all code must pass it cleanly. Suppressing a lint error requires the same effort as fixing the underlying issue, so you must always choose to fix the issue.
Every non-trivial task must begin with a written plan. The plan must be atomic, specific, and verifiable. Each step must be small enough that its correctness is obvious.
When writing code in any language:
- Read the core protocol (
AGENTS/AGENTS.md) to understand the universal principles. - Read the relevant satellite file for your language or topic.
- Follow the required linters and tools listed in the satellite file.
- Apply the best practices and avoid the common mistakes documented.
- Use the operational workflow (Plan, Confirm, Execute, Report) for all non-trivial tasks.
When reviewing agent code:
- Verify that the agent has read and followed the relevant satellite file.
- Check that all required linters pass cleanly with no suppressions.
- Ensure that error messages are useful and that the code fails fast and hard.
- Confirm that the agent followed the PLAN.md workflow if the task was non-trivial.
- Use the "Message to a Reviewing Agent" template when delegating review to another agent.
To integrate the AGENTS protocol into a project:
- Clone this repository or copy the relevant satellite files into your project documentation.
- Configure CI/CD to run the required linters for each language used.
- Train agents and developers on the protocol before they begin writing code.
AGENTS/AGENTS.md— Core protocol with universal principles and operational workflowAGENTS/*.AGENTS.md— Language-specific and topic-specific satellite filesREADME.md— This file
This protocol is provided as-is for use in AI agent coding and dev education.
This is a reference protocol. Changes should be made with careful consideration of their impact on agent behavior and code quality. Suggestions for improvements should be grounded in real-world experience with agent-generated code.