From f41a6cbe875a40ee80d390da89a6488d84f2e18e Mon Sep 17 00:00:00 2001
From: Dmitrii <me@dementev.space>
Date: Fri, 17 Apr 2026 18:44:04 +0300
Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB?=
 =?UTF-8?q?=D0=B5=D0=BD=20AGENTS.md=20=D0=B4=D0=BB=D1=8F=20orientation=20A?=
 =?UTF-8?q?I-=D0=B0=D0=B3=D0=B5=D0=BD=D1=82=D0=BE=D0=B2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Зачем:
  - конвенция AGENTS.md (codex, aider и др. агенты её автодетектят) даёт свежему агенту быструю навигацию по репо без прочтения всех 50 KB DESIGN.md перед началом работы.
- Что:
  - Короткий (~25 строк) pointer-файл: one-paragraph what-is-this, три main-docs с one-line описанием, три "don't"-правила про cross-refs / session marker / silent-recovery, верификация через §7 smoke-test + dogfood.
  - Всё содержательное остаётся в DESIGN.md; AGENTS.md только ориентирует.
- Проверка:
  - Файл существует, читаем, ссылается на реальные §-номера в DESIGN.md (§4.1b, §6.7, §6.8, §7, §9.6, §10).
---
 AGENTS.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..4b65e3e
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,26 @@
+# AGENTS.md
+
+Orientation for AI coding agents working on this repo.
+
+## What this is
+
+A Claude Code skill that orchestrates adversarial review: Claude writes an adversarial prompt, launches OpenAI Codex as an external reviewer, shows the findings to the user, applies fixes, and iterates up to 5 rounds until approved. This is **not a regular codebase** — the product is a single instruction file (`SKILL.md`) executed by Claude Opus at runtime.
+
+## Where to look
+
+- **README.md** — user-facing: install, permissions, troubleshooting.
+- **SKILL.md** — the instruction template Opus executes. Uses `${PLACEHOLDER}` syntax for runtime substitution (not shell variables). Step ordering is load-bearing.
+- **docs/DESIGN.md** — the "why" behind every non-obvious decision, rejected alternatives, verification protocol (§7 smoke tests), and the update protocol (§10). Read §10 before modifying SKILL.md.
+- **examples/** — sample outputs. Not source of truth.
+
+## Before you change things
+
+- Don't renumber DESIGN.md sections — cross-refs across all three files break silently (§10.2).
+- Don't remove the session marker `<!-- ADVERSARIAL-REVIEW-SESSION: ${REVIEW_ID}-${ATTEMPT_ID} -->` from prompt templates — the session-id fallback depends on it (§4.1b).
+- Don't add silent-recovery fallbacks. The skill's explicit preference is fail-closed over masked failure (§6.7, §6.8).
+
+## Verifying a change
+
+- Smoke test: `docs/DESIGN.md §7` — copy-paste bash, runs in ~2 minutes.
+- End-to-end: dogfood via `/adversarial-review code` against any branch with commits vs master.
+- No automated CI (§9.6 explains why).