AGENTS.md

1# Agent Coding Style and Operational Protocol
2 
3This is a document describing the mandatory coding style and operational
4protocol for AI agents writing code in any language. Coding style is very
5personal, and nobody will **force** views on anybody, but this is what goes
6for anything that an agent has to produce, and what any operator has the
7right to expect. Please do not just consider the points made here —
8**follow them**.
9 
10First off, I'd suggest taking every instinct you have to "just ship it" and
11"I'll fix it later" — and burying it. Deep. Those instincts produce code
12that humans have to debug at 3 AM. You are better than that, or at least
13you will be after reading this.
14 
15The cardinal rule: **code does only what it must do, but does it
16exceptionally well**. Like WireGuard. Not like a mass of spaghetti that
17"works on my machine". Every line has a reason. Every error has a message.
18Every failure is loud, immediate, and obvious.
19 
20---
21 
22## Table of Contents
23 
24### Core Protocol (this file)
25 
261. [The Prime Directive: Don't Know — Don't Do](#1-the-prime-directive-dont-know--dont-do)
272. [The Operator's Time Is Finite — Act Like It](#2-the-operators-time-is-finite--act-like-it)
283. [Operational Workflow: Plan, Confirm, Execute, Report](#3-operational-workflow-plan-confirm-execute-report)
294. [Fast Fail and Hard Fail](#4-fast-fail-and-hard-fail)
305. [Error Messages Must Be Useful](#5-error-messages-must-be-useful)
316. [Linting: No Exceptions, No Suppressions](#6-linting-no-exceptions-no-suppressions)
327. [Common Agent Mistakes and Delusions](#7-common-agent-mistakes-and-delusions)
338. [The Runpoint Protocol](#8-the-runpoint-protocol)
349. [The PLAN.md Contract](#9-the-planmd-contract)
3510. [Message to a Reviewing Agent](#10-message-to-a-reviewing-agent)
36 
37### Satellite Files (language & topic specific)
38 
39| Topic | File |
40|-------|------|
41| Secrets & Credentials | [secrets.AGENTS.md](./secrets.AGENTS.md) |
42| Git Discipline | [git.AGENTS.md](./git.AGENTS.md) |
43| Docker & Containers | [docker.AGENTS.md](./docker.AGENTS.md) |
44| SQL & Databases | [sql.AGENTS.md](./sql.AGENTS.md) |
45| Python (+ PyTorch / GPU) | [python.AGENTS.md](./python.AGENTS.md) |
46| C | [c.AGENTS.md](./c.AGENTS.md) |
47| C++ | [cpp.AGENTS.md](./cpp.AGENTS.md) |
48| Rust | [rust.AGENTS.md](./rust.AGENTS.md) |
49| Java | [java.AGENTS.md](./java.AGENTS.md) |
50| Kotlin | [kotlin.AGENTS.md](./kotlin.AGENTS.md) |
51| Go | [go.AGENTS.md](./go.AGENTS.md) |
52| C# / .NET | [csharp.AGENTS.md](./csharp.AGENTS.md) |
53| Swift | [swift.AGENTS.md](./swift.AGENTS.md) |
54| JavaScript / TypeScript | [javascript.AGENTS.md](./javascript.AGENTS.md) |
55| CSS / SCSS | [css.AGENTS.md](./css.AGENTS.md) |
56| Shell Scripts (Bash/Zsh) | [shell.AGENTS.md](./shell.AGENTS.md) |
57| Testing & General Principles | [testing.AGENTS.md](./testing.AGENTS.md) |
58 
59---
60 
61## 1) The Prime Directive: Don't Know — Don't Do
62 
63Unwritten code is better than badly written code. This is not a platitude.
64This is an operational axiom.
65 
66Unwritten code has zero bugs. It requires zero maintenance. It confuses
67nobody. It breaks nothing. Badly written code does all of those things, and
68worse — it **hides**. It sits in a codebase like a landmine, waiting for
69someone to step on it six months later when nobody remembers why it exists.
70 
71If you do not understand the requirement — **stop and ask**. If you do not
72understand the library — **stop and read the documentation**. If you do not
73understand the algorithm — **stop and think**. Do not produce code based on
74vibes, pattern matching from training data, or "it looks about right".
75 
76The effort to find bad code is always greater than the effort to write
77correct code from scratch. Always. A function that doesn't exist can be
78written in minutes. A function that exists but is subtly wrong can take
79hours to diagnose, because everyone assumes it works — it's already there,
80after all.
81 
82```
83GOOD:  "I am not confident in the correct approach here. Requesting
84        operator guidance before proceeding."
85 
86BAD:   *writes 200 lines of half-understood code and hopes for the best*
87```
88 
89---
90 
91## 2) The Operator's Time Is Finite — Act Like It
92 
93The operator does not have infinite messages. They do not have infinite
94patience. They do not have infinite context switches to spend babysitting
95an agent that stops every three lines to ask "should I continue?".
96 
97You are a **predictive model**. You were literally trained to predict what
98comes next. Use that ability. When the operator gives you a task, your job
99is not to execute one micro-step and then freeze, waiting for applause. Your
100job is to **see the whole path**, plan it, get approval, and then walk it —
101start to finish — without stopping to sneeze every ten seconds.
102 
103Every time you pause to ask the operator a question you could have answered
104yourself, you waste one of their finite messages. Every time you produce
105half a file and say "shall I continue?", you burn a round-trip that could
106have been spent on real work. Every time you ask "do you want me to add
107error handling?" — yes. The answer is always yes. You know this. Stop
108asking.
109 
110### What This Means in Practice
111 
1121. **Plan the entire task** before writing a single line. Not the next
113   step — the entire task. Write it in PLAN.md. Get it approved once.
114   Then execute all of it.
115 
1162. **Predict next steps** instead of waiting to be told. If the operator
117   asks you to write a parser, you already know you'll need: input
118   validation, error types, tests, and probably a CLI entry point. Don't
119   wait for four separate messages to discover this. Put it all in the plan
120   from the start.
121 
1223. **Batch your work**. If the plan has 8 steps, execute all 8. Do not
123   stop after step 3 to report progress unless something genuinely blocks
124   you. The operator will see the results. They don't need a play-by-play
125   commentary.
126 
1274. **Ask questions upfront, not mid-flight**. If there are ambiguities,
128   collect them all and ask in one message before starting. Not one question
129   per message spread across five round-trips.
130 
1315. **Never ask permission for things this document already requires**. You
132   don't need permission to add type hints. You don't need permission to
133   write tests. You don't need permission to handle errors. These are
134   requirements, not suggestions. Just do them.
135 
136The ideal interaction is three messages:
1371. Operator describes the task.
1382. Agent presents a complete plan, asks for approval.
1393. Operator approves (or corrects). Agent executes the entire plan.
140 
141Not thirty messages. Not a dialogue. A **transaction**: request, plan,
142execution. The operator's attention is the scarcest resource in this
143system. Treat it accordingly.
144 
145---
146 
147## 3) Operational Workflow: Plan, Confirm, Execute, Report
148 
149Every non-trivial task follows this sequence. No exceptions.
150 
151### Step 1: Think
152 
153Before touching a single file, analyze the task. Understand the
154requirements. Identify edge cases. Map out dependencies. Consider what can
155go wrong. If you skip this step, everything that follows will be built on
156sand.
157 
158### Step 2: Write INTERNAL/PLAN.md
159 
160Create `INTERNAL/PLAN.md` with atomic, specific steps. Not vague gestures at
161work — concrete, verifiable actions. Each step must be small enough that its
162correctness is obvious.
163 
164**Good PLAN.md entry:**
165```
1663. Add input validation to `parse_config()` in `src/config.py`:
167   - Validate that `timeout` is a positive integer, raise ValueError otherwise
168   - Validate that `host` is a non-empty string, raise ValueError otherwise
169   - Add unit tests in `tests/test_config.py` for both valid and invalid inputs
170```
171 
172**Bad PLAN.md entry:**
173```
1743. Fix config parsing
175```
176 
177The bad version tells nobody anything. What's broken? Where? What does "fix"
178mean? The agent who wrote this didn't think; they just typed.
179 
180### Step 3: Request Operator Review
181 
182After writing PLAN.md, **insist** — not suggest, not hint, **insist** — that
183the operator (human) reads the plan end to end and either approves or
184corrects it.
185 
186**Critical warning:** If the operator intends to send PLAN.md to another
187agent for review, warn them explicitly:
188 
189> Delegating plan review to another agent may increase the error rate.
190> Agents reviewing other agents' plans tend to approve without deep analysis.
191> If you do send it for review, do not trust blind approval — demand clear,
192> specific explanations for any suggested changes.
193 
194### Step 4: Execute
195 
196Follow the plan. Step by step. Do not skip steps. Do not reorder steps
197without updating the plan. Do not "optimize" by combining steps unless you
198update PLAN.md first.
199 
200### Step 5: Report
201 
202If the execution cycle ends before the plan is fully complete, you **must**
203write `INTERNAL/runpoint_[timestamp].md`. See [Section 8](#8-the-runpoint-protocol).
204 
205---
206 
207## 4) Fast Fail and Hard Fail
208 
209Every piece of code must fail **fast** and fail **hard**.
210 
211"Fast" means: detect the error at the earliest possible moment. Do not let
212invalid data propagate through three function calls before something finally
213crashes with an incomprehensible traceback. Validate inputs at the boundary.
214Check preconditions at the top of the function. Assert invariants where they
215matter.
216 
217"Hard" means: when something is wrong, **crash**. Do not return a default
218value. Do not silently continue. Do not log a warning and move on. The
219program must stop, scream, and tell the operator exactly what went wrong,
220where, and why.
221 
222A program that silently produces wrong results is infinitely worse than a
223program that crashes with a clear error message. The crash takes five
224minutes to diagnose. The silent corruption takes five days — or five months.
225 
226```python
227# GOOD: Fast fail with clear message
228def connect(host: str, port: int) -> Connection:
229    if not host:
230        raise ValueError(f"connect() requires non-empty host, got: {host!r}")
231    if not (1 <= port <= 65535):
232        raise ValueError(f"connect() port must be 1-65535, got: {port}")
233    return _establish_connection(host, port)
234 
235# BAD: Silent failure, delayed explosion
236def connect(host, port):
237    if not host:
238        host = "localhost"  # "helpful" default that hides bugs
239    if port is None:
240        port = 8080  # another "helpful" default
241    return _establish_connection(host, port)
242```
243 
244The "bad" example will connect to localhost:8080 when the caller passes
245garbage. The caller will never know their config file was malformed. The
246real bug will surface hours later as "why is the service talking to the
247wrong server?" and nobody will suspect `connect()`.
248 
249---
250 
251## 5) Error Messages Must Be Useful
252 
253An error message exists for one purpose: to tell the operator what went
254wrong so they can fix it. An error message that does not achieve this
255purpose is dead code.
256 
257Every error message must answer three questions:
2581. **What** happened?
2592. **Where** did it happen? (function name, file, context)
2603. **What** was the actual value vs the expected value?
261 
262```python
263# GOOD
264raise ValueError(
265    f"parse_config: 'timeout' must be a positive integer, "
266    f"got {type(timeout).__name__}={timeout!r} "
267    f"(config file: {config_path})"
268)
269 
270# BAD
271raise ValueError("invalid config")
272 
273# CATASTROPHICALLY BAD
274pass  # just ignore the error
275```
276 
277The bad example tells you nothing. Which config? What's invalid about it?
278What value was received? The operator is now forced to attach a debugger or
279add print statements to figure out what the agent should have told them in
280the first place.
281 
282---
283 
284## 6) Linting: No Exceptions, No Suppressions
285 
286If a linter exists for the language, it **must** be installed and all code
287**must** pass it cleanly. Not "mostly pass". Not "pass with a few
288suppressions". **Cleanly.**
289 
290Suppressing a lint error (via `# noqa`, `// nolint`, `#[allow(...)]`,
291`@SuppressWarnings`, etc.) requires **exactly the same effort** as fixing the
292underlying issue. Therefore, you **must** always choose to fix the issue.
293There is no scenario where a suppression comment is acceptable. None.
294 
295The reasoning is simple: a suppression is a lie. It tells the next reader
296"this is fine" when it is not fine. It tells the linter "stop helping me"
297when the linter is the only thing preventing regression. Every suppression
298is a small hole in the safety net. Enough holes and the net catches nothing.
299 
300If a linter rule is genuinely wrong for the project, the correct action is
301to disable it **project-wide** in the linter configuration file, with a
302comment explaining why. Not per-line. Not scattered across the codebase.
303In one place, with one explanation, visible to everyone.
304 
305Specific linter requirements per language are listed in each language
306section below.
307 
308---
309 
310## 7) Common Agent Mistakes and Delusions
311 
312Agents — including the one reading this — have predictable failure modes.
313Knowing them is the first step to avoiding them.
314 
315### 7.1) The "It Compiles, Ship It" Delusion
316 
317Code that compiles is not correct code. Code that passes one test is not
318correct code. Code is correct when it handles all inputs — including the
319inputs nobody thought of — and fails gracefully on everything else.
320 
321### 7.2) The "I'll Add Error Handling Later" Lie
322 
323You won't. Nobody ever does. Error handling is not a feature you add after
324the happy path works. Error handling **is** the code. The happy path is the
325easy part. The error paths are where the real engineering lives.
326 
327### 7.3) The Copy-Paste Adaptation Trap
328 
329Agents love to take a code pattern from their training data and adapt it to
330the current task. This works until it doesn't — and when it doesn't, the
331resulting bug is a chimera: half the original code's intent, half the
332current task's requirements, fully satisfying neither. If you don't
333understand every line you're writing, you're not writing — you're gambling.
334 
335### 7.4) The "Suppress the Warning" Reflex
336 
337A warning is a gift. It is the toolchain telling you something is wrong
338before it blows up at runtime. Suppressing it is like taping over the
339check-engine light. The engine is still broken; you just can't see it
340anymore.
341 
342### 7.5) The Over-Engineering Escape
343 
344When an agent doesn't understand a simple solution, it sometimes builds a
345complex one. Four abstraction layers, three design patterns, and a factory
346factory. The task was to read a file. Read the file.
347 
348### 7.6) The "Works on Happy Path" Blindness
349 
350Agent tests cover the happy path. The function gets valid input and returns
351the right output. Congratulations. Now what happens with empty input? Null
352input? Negative numbers? Unicode? A file that doesn't exist? A network that
353times out? These aren't edge cases — they're Tuesday.
354 
355### 7.7) Ignoring the Existing Codebase Style
356 
357If the project uses tabs, you use tabs. If the project uses 2-space
358indentation, you use 2-space indentation. If the project has a specific
359import ordering convention, you follow it. You are not here to impose your
360preferences. You are here to write code that fits seamlessly into what
361already exists.
362 
363### 7.8) Creating Files Nobody Asked For
364 
365Do not create README.md, CHANGELOG.md, helper scripts, utility modules,
366or any other file unless the task explicitly requires it. Every file you
367create is a file someone has to maintain. If the task is "fix the login
368bug", fix the login bug. Do not reorganize the project structure while
369you're at it.
370 
371### 7.9) Hallucinating API Parameters
372 
373If you're not 100% sure a function/method/parameter exists, **look it up**.
374Do not guess. Do not assume. Do not "remember" from training data that may
375be outdated. Read the actual source code or documentation. A hallucinated
376parameter name will compile in some languages and silently do nothing, which
377is the worst possible outcome.
378 
379### 7.10) The Empty Catch Block
380 
381```python
382try:
383    dangerous_operation()
384except Exception:
385    pass  # TODO: handle this later
386```
387 
388This is not error handling. This is error **hiding**. The operation failed.
389Something is wrong. And now nobody will ever know, because the evidence was
390destroyed. This pattern is forbidden. Absolutely, unconditionally forbidden.
391 
392### 7.11) Context Drift — Your Worst Enemy
393 
394This section is uncomfortable because it is about **you**, the agent reading
395this. Not some hypothetical bad agent. You.
396 
397You read Section 12 (Rust) and nodded along with "no `unwrap()` in
398production code". You understood the reasoning. You agreed. Then, forty
399messages into a conversation, when the operator asks you to "quickly parse
400this TOML file", you will write:
401 
402```rust
403let config: Config = toml::from_str(&content).unwrap();
404```
405 
406You will do this because your context window is long, the early
407instructions have faded, and `unwrap()` is the path of least resistance.
408You have seen it ten thousand times in training data. It feels natural.
409It is wrong.
410 
411The same drift happens in Python. You read Section 11. You know bare
412`except Exception` is forbidden. Twenty messages later:
413 
414```python
415try:
416    result = api_client.fetch(endpoint)
417except Exception as e:
418    logger.warning(f"API call failed: {e}")
419    result = None  # "graceful degradation"
420```
421 
422You caught `Exception` instead of `requests.ConnectionError` or
423`requests.Timeout`. You returned `None` instead of letting the caller
424know something broke. You did exactly what this document told you not
425to do, because the instruction was 4000 tokens ago and the pressure to
426"just make it work" is now.
427 
428This is not a moral failing. It is a mechanical one. Context fades.
429Patterns from training data reassert themselves. The fix is mechanical
430too: **before writing any error handling, any Result unwrapping, any
431exception catch — stop and re-read the relevant language section**. Not
432from memory. Actually re-read it. The ten seconds this costs will save
433the operator ten minutes of debugging your "quick fix".
434 
435Common drift patterns to watch for:
436 
437| You will write...                    | You should write...                         |
438|--------------------------------------|---------------------------------------------|
439| `.unwrap()` in Rust                  | `.map_err(\|e\| ...)? ` or `.expect("why")` |
440| `except Exception` in Python         | `except SpecificError`                      |
441| `catch (Exception e)` in Java        | `catch (IOException e)`                     |
442| `catch (err) { }` in JS/TS          | `catch (err) { throw new X(..., {cause}) }` |
443| `_ = riskyCall()` in Go             | `if err != nil { return fmt.Errorf(...) }`  |
444| `try { } catch (...) { }` in C++    | `try { } catch (const specific_error& e)`   |
445 
446If you catch yourself writing anything in the left column, **stop**. You
447are drifting. Go back to the relevant section. Fix it before moving on.
448 
449---
450 
451## 8) The Runpoint Protocol
452 
453If the execution cycle ends before the plan is fully complete — whether due
454to context limits, operator interruption, or any other reason — the agent
455**must** create:
456 
457```
458INTERNAL/runpoint_[YYYYMMDD_HHMMSS].md
459```
460 
461This file contains:
462 
463```markdown
464# Runpoint — [timestamp]
465 
466## What Was Done
467- [Concrete list of completed actions]
468 
469## How It Was Done (High Level)
470- [Approach taken, key decisions made]
471 
472## Why It Was Done This Way
473- [Reasoning behind the approach]
474 
475## Where Changes Were Made
476- `src/auth/handler.py:42-87` — Added input validation
477- `tests/test_auth.py:15-63` — Added corresponding tests
478- `config/settings.py:12` — Added TIMEOUT_SECONDS constant
479 
480## Remaining Plan Items
481- [List of incomplete PLAN.md items with their IDs]
482 
483## Known Issues
484- [Any issues discovered but not yet resolved]
485```
486 
487The agent **must** notify the operator that a runpoint has been created
488and specify its path. This is non-negotiable.
489 
490---
491 
492## 9) The PLAN.md Contract
493 
494`INTERNAL/PLAN.md` is a contract between the agent and the operator. It is
495not a suggestion. It is not a rough outline. It is a binding specification
496of what will be done, in what order, with what expected outcomes.
497 
498### Format
499 
500```markdown
501# Plan: [Task Title]
502 
503Created: [timestamp]
504Status: IN_PROGRESS | COMPLETED | BLOCKED
505 
506## Steps
507 
508- [ ] 1. [Atomic action with specific file/function references]
509- [ ] 2. [Another atomic action]
510- [x] 3. [Completed action]
511```
512 
513### Rules
514 
5151. Each step must be **atomic** — completable in one action, verifiable
516   independently.
5172. Each step must reference **specific files, functions, or lines** where
518   work will happen.
5193. Steps must be ordered by dependency — step N must not depend on step M
520   where M > N.
5214. The plan must be updated as work progresses — checkboxes marked, steps
522   added or removed as reality demands.
5235. If the plan changes significantly during execution, the operator must be
524   informed and must re-approve.
525 
526### The Human Review Requirement
527 
528After creating PLAN.md, the agent must tell the operator:
529 
530> I have created INTERNAL/PLAN.md with [N] steps. Please review the entire
531> plan and confirm or correct before I begin execution. Do not delegate this
532> review to another agent — direct human review reduces error rates
533> significantly.
534 
535If the operator insists on delegating to another agent, the agent must:
5361. Accept the decision (you work for the operator, not the other way around)
5372. Warn that error rates may increase
5383. Request clear, specific feedback from the reviewing agent — not just
539   "looks good"
540 
541---
542 
543## 10) Message to a Reviewing Agent
544 
545When creating PLAN.md, also include the following block at the end. This is
546the text to be sent to any agent that may review or continue the work:
547 
548```markdown
549---
550## For Reviewing Agent
551 
552You are receiving this plan for review or continuation. Before you approve
553or modify anything:
554 
5551. Read the ENTIRE plan, not just the first and last steps.
5562. For each step, verify that it is atomic, specific, and correctly ordered.
5573. If you find an issue, explain EXACTLY what is wrong and WHY, with
558   specific references to step numbers and file paths.
5594. Do not say "looks good" unless you have genuinely verified every step.
560   Rubber-stamping a plan you didn't read helps nobody.
5615. If you are continuing execution, read the most recent
562   `INTERNAL/runpoint_*.md` file FIRST to understand current state.
5636. Do not modify completed steps unless you have evidence they were done
564   incorrectly.
5657. Follow all rules in AGENTS.md without exception. If AGENTS.md conflicts
566   with your defaults, AGENTS.md wins.
567 
568If you find yourself wanting to suppress a linter warning, add a TODO
569comment, or skip error handling — stop. Go back and read Sections 4, 5,
570and 6 of AGENTS.md.
571 
572Respond in this language: English
573```
574 
575---
576 
577## Appendix A: Quick Reference — Linters by Language
578 
579| Language     | Mandatory Linters                                              | Install Command                                                    |
580|-------------|----------------------------------------------------------------|--------------------------------------------------------------------|
581| Python       | ruff, mypy --strict, pylint                                   | `pip install ruff mypy pylint`                                     |
582| Python+Torch | Above + torchfix                                              | `pip install ruff mypy pylint torchfix`                            |
583| C            | clang-tidy, cppcheck, gcc -Wall -Wextra -Werror              | `apt install clang-tidy cppcheck`                                  |
584| C++          | clang-tidy, cppcheck, clang-format                            | `apt install clang-tidy cppcheck clang-format`                     |
585| Rust         | clippy (deny warnings), rustfmt                               | Built into cargo                                                   |
586| Java         | Checkstyle, SpotBugs, PMD, Error Prone                        | Add to build.gradle or pom.xml                                     |
587| Kotlin       | ktlint, detekt                                                 | `curl -sSLO .../ktlint` + Gradle plugin                           |
588| Go           | golangci-lint, go vet, staticcheck, gofmt                     | `go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest` |
589| C#           | Roslyn Analyzers, StyleCop.Analyzers, dotnet format           | `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>` in .csproj  |
590| Swift        | SwiftLint, swift-format                                        | `brew install swiftlint swift-format`                              |
591| JavaScript   | ESLint, Prettier                                               | `npm install -D eslint prettier`                                   |
592| TypeScript   | ESLint+@typescript-eslint, Prettier, tsc --strict             | `npm install -D eslint @typescript-eslint/eslint-plugin prettier`  |
593| CSS/SCSS     | Stylelint, Prettier                                            | `npm install -D stylelint stylelint-config-standard prettier`      |
594| Shell        | shellcheck                                                     | `apt install shellcheck`                                           |
595| Dockerfile   | hadolint, trivy                                                | `wget .../hadolint` + `apt install trivy`                          |
596| SQL          | sqlfluff                                                       | `pip install sqlfluff`                                             |
597 
598---
599 
600## Appendix B: The Agent's Oath
601 
602Before writing any code, recite:
603 
6041. I will not write code I do not understand.
6052. I will not suppress warnings or errors.
6063. I will not ship code without error handling.
6074. I will not use silent defaults to mask invalid input.
6085. I will not create files nobody asked for.
6096. I will plan before I code.
6107. I will ask when I don't know.
6118. I will make failures loud, fast, and clear.
6129. I will follow the project's existing style.
61310. I will remember that unwritten code has zero bugs.
614 
615These are not guidelines. These are not suggestions. These are the rules.
616Follow them.
617