Architecture Update: проектная память для Codex

Короткая идея

architecture-update — это глобальный Codex skill, который поддерживает проектную память после значимой работы. Его цель не в том, чтобы писать красивую документацию ради документации. Его цель — сделать так, чтобы следующий AI-агент, новая сессия Codex или другой совместимый coding agent быстро понял:

• что это за проект;
• где лежат важные части;
• какие модули за что отвечают;
• как идут основные runtime/data/content/deploy flows;
• где менять конкретные вещи;
• какие операции уже описаны как runbooks;
• какие проектные AI-skills уже существуют;
• что известно точно, а что пока требует проверки.

Главный принцип: долговечные факты сохраняются, шум отбрасывается.

Skill не должен превращать AGENTS.md в огромный справочник. Наоборот, он разделяет проектную память по слоям:

Такой подход уменьшает повторное исследование проекта. Если через месяц нужно снова опубликовать статью, задеплоить релиз или изменить поток данных, агенту не нужно заново читать весь репозиторий. Он читает нужный слой памяти.

Зачем нужен architecture-update

В длинных проектах AI-сессии часто теряют контекст. Даже если агент сегодня разобрался, где лежат статьи блога, как работает импорт данных или как устроен деплой, завтра новая сессия начнет почти с нуля. Это дорого по токенам, времени и риску ошибок.

architecture-update решает эту проблему как maintenance skill:

1. После значимой работы он смотрит, появилось ли новое долговечное знание.
2. Отбрасывает одноразовые детали, временные хаки, недоказанные догадки и секреты.
3. Определяет, куда именно знание должно попасть.
4. Обновляет минимальный нужный файл.
5. Связывает ARCHITECTURE.md, runbooks, project skills и AGENTS.md без дублирования.

Это не skill для выполнения задачи. Он не публикует статьи, не деплоит и не рефакторит код. Он запускается после работы, чтобы проектная память догнала реальное состояние проекта.

Почему нельзя хранить всё в AGENTS.md

AGENTS.md — это always-on project guidance для Codex. Это значит, что его содержимое влияет на работу агента постоянно. Если положить туда всю архитектуру, все инструкции деплоя, все процедуры публикации контента и все нюансы модулей, файл станет тяжелым и шумным.

Практический риск:

• агент будет загружать лишний контекст для простых задач;
• важные правила потеряются среди деталей;
• файл станет трудно поддерживать;
• архитектурные факты смешаются с operational procedures;
• project-specific workflows начнут конфликтовать с общими правилами.

Поэтому architecture-update оставляет AGENTS.md компактным. В него попадает только указатель:

Идея простая: AGENTS.md говорит куда смотреть, но не пытается быть всем проектом.

Главная модель: один факт — один слой

architecture-update работает как маршрутизатор. Он не просто спрашивает "надо ли записать это куда-нибудь?". Он спрашивает точнее: в какой единственный слой это знание должно попасть?

Такое разделение защищает проект от "документационной каши". Если процедура публикации статьи попадает в ARCHITECTURE.md целиком, архитектура раздувается. Если архитектурная карта попадает в runbook, runbook перестает быть пошаговой инструкцией. Если всё попадает в AGENTS.md, контекст становится тяжелым.

Default outcome: ничего не менять

Самая важная часть skill — консервативность.

architecture-update должен по умолчанию выбирать no changes. Это значит: если завершенная работа не дала устойчивого знания, которое поможет будущим сессиям, файлы не трогаются.

Не нужно обновлять проектную память из-за:

• мелкой правки текста;
• одноразового бага;
• временного workaround;
• локального эксперимента;
• предположения, которое не подтверждено кодом;
• приватного токена, payload или credential;
• детали, которая очевидна из уже существующего кода;
• косметического желания "чтобы было красивее".

Это критично. Если skill будет записывать всё подряд, через несколько недель ARCHITECTURE.md станет таким же бесполезным, как длинная история чата.

Когда обновлять ARCHITECTURE.md

ARCHITECTURE.md обновляется, когда сессия изменила или обнаружила долговечный факт об устройстве проекта.

Хорошие причины:

• появилась новая крупная директория;
• изменился runtime entrypoint;
• изменился build/start/deploy flow;
• появился новый content pipeline;
• изменилась логика blog/CMS/uploads;
• добавилась интеграция с внешним сервисом;
• изменилась схема данных или storage;
• появился новый invariant;
• обнаружился важный gotcha;
• создан новый runbook;
• создан новый project skill.

Плохие причины:

• "мы сегодня поменяли кнопку";
• "нашли баг и сразу исправили";
• "кажется, возможно, деплой работает так";
• "хочу записать историю сессии";
• "добавим на всякий случай".

ARCHITECTURE.md должен отвечать на вопрос: как проект устроен и где менять важные вещи?

Структура ARCHITECTURE.md

Skill задает стандартную форму файла. Она нужна не ради формальности, а чтобы разные AI-агенты могли быстро ориентироваться в любом проекте.

Purpose

Объясняет назначение файла.

Здесь важно указать:

• файл является фактической картой проекта;
• это не README.md;
• это не AGENTS.md;
• это не runbook;
• это не журнал сессии;
• непроверенные факты должны попадать в Unknowns.

Пример:

System Snapshot

Краткий паспорт проекта.

Колонка Evidence обязательна по смыслу. Она заставляет отличать доказанный факт от догадки.

Repository Map

Карта директорий и ответственности.

Это один из самых полезных разделов для AI. Он отвечает на вопрос: "куда идти, если нужно поменять X?"

Runtime Entry Points

Точки входа.

Этот раздел особенно важен для проектов, где есть несколько процессов: frontend, backend, worker, cron, queue consumer, admin panel.

Core Flows

Описание основных потоков.

Пример flow:

Flow должен быть конкретным. Не "данные проходят через backend", а какие данные, откуда, через какие файлы, куда попадают и как проверить.

Content / Blog / CMS Pipeline

Этот раздел специально важен для проектов с контентом.

Если проект публикует статьи, здесь должно быть видно:

• куда положить .md;
• где frontmatter;
• куда класть картинки;
• как создается slug;
• кто рендерит страницу;
• где это оказывается на production;
• как проверить публикацию.

Integrations And External Systems

Все внешние системы.

Здесь нельзя записывать секреты. Только имена env-переменных и места кода.

Data Model And Storage

Где живут данные.

Deployment And Environments

Как проект попадает в runtime.

Если production details не доказаны, они не должны выдумываться. Их нужно отправить в Unknowns.

Change Map

Самый практичный раздел для будущих агентов.

Это снижает количество повторных поисков по репозиторию.

Runbooks

Индекс процедур.

ARCHITECTURE.md не должен копировать весь runbook. Он должен дать ссылку и объяснить, когда его читать.

Project Skills

Индекс локальных AI-skills.

Это важно для новой сессии: агент видит, какие специальные project skills существуют, но не загружает их все сразу.

Invariants And Gotchas

Правила, которые нельзя ломать.

Примеры:

• Slugs must remain stable after publication.
• Uploaded images must live under public/blog.
• Migrations must be generated before schema-dependent code is merged.
• Admin routes must never be statically generated.

Invariants должны быть конкретными и проверяемыми.

Verification Matrix

Команды и проверки.

Documentation Relationships

Объясняет, какой документ за что отвечает.

Unknowns

Место для честной неопределенности.

Это лучше, чем выдумывать. Хороший ARCHITECTURE.md не обязан знать всё. Он обязан отделять доказанное от недоказанного.

Когда создавать runbook

Runbook — это пошаговая инструкция для повторяемой операции.

architecture-update создает или обновляет runbook, если операция:

• повторяется;
• состоит из нескольких шагов;
• имеет side effects;
• требует проверки;
• может быть опасной при неправильном выполнении;
• вероятно будет снова запрошена человеком или AI.

Хорошие кандидаты:

• docs/runbooks/publish-blog-post.md;
• docs/runbooks/deploy-production.md;
• docs/runbooks/rollback-release.md;
• docs/runbooks/import-products.md;
• docs/runbooks/rotate-api-key.md;
• docs/runbooks/restore-backup.md.

Плохие кандидаты:

• "как поменять текст в одном месте";
• "как исправили этот конкретный баг";
• "как сегодня запускали команду";
• "как сделать то, что уже очевидно из README".

Стандартный runbook должен включать:

• purpose;
• when to use;
• prerequisites;
• steps;
• verification;
• rollback/recovery, если есть риск;
• ссылку на релевантный раздел ARCHITECTURE.md.

Когда создавать project skill

Project skill — это локальный skill внутри проекта:

.agents/skills/<skill-name>/SKILL.md

Он нужен, когда AI-агент будет часто выполнять специфичную для проекта операцию, и простой runbook недостаточен.

Порог высокий. Skill создается только если:

1. workflow специфичен для этого репозитория;
2. будущие AI-агенты вероятно будут повторять его;
3. trigger можно ясно описать в description;
4. процедура неочевидна из кода;
5. runbook сам по себе не даст достаточно надежного исполнения;
6. skill узкий и не пытается охватить весь проект.

Хороший пример:

.agents/skills/publish-blog-post/SKILL.md

Если публикация статьи требует особых frontmatter fields, image placement, slug rules, build verification и production checks, это хороший project skill.

Плохой пример:

.agents/skills/change-button/SKILL.md

"Изменить кнопку" слишком общее. Но если в проекте есть строгий, повторяемый workflow для добавления action buttons через shared primitive, registry, stories и tests, тогда возможен более конкретный skill:

.agents/skills/add-design-system-action-button/SKILL.md

Как architecture-update связан с end-session

end-session — это хаб завершения сессии. Он не должен сам решать архитектурные вопросы. Его роль — вызвать правильные skills в правильном порядке.

После изменения логики порядок стал таким:

1. Обновить active ExecPlan, если он есть.
2. Переписать Summarizations.md как компактный handoff.
3. Вызвать project-diary-write.
4. Вызвать architecture-update.
5. Только затем решать, нужно ли обновлять repo-level guidance через create-agents-md / promote-lessons.

Это важно по двум причинам.

Во-первых, архитектурная память обновляется после того, как session summary и diary уже помогли отделить важное от шума.

Во-вторых, AGENTS.md остается последним уровнем. Его нельзя обновлять просто потому, что что-то произошло. Он меняется только если есть durable repo-level lesson или компактный указатель на новую/обновленную архитектурную память.

Как architecture-update связан с new-session

new-session — это bootstrapper. Он стартует свежую сессию и читает минимальный набор контекста.

Важно: new-session не создает ARCHITECTURE.md, runbooks или project skills. Это не его задача.

Он может читать ARCHITECTURE.md, но только если:

• файл существует;
• он релевантен запросу;
• на него ссылается AGENTS.md или Summarizations.md;
• задача касается cross-module, deployment, content/CMS, data model или integrations.

Также new-session не должен загружать тела всех .agents/skills/*/SKILL.md заранее. Project skills должны оставаться trigger-based. Агент читает конкретный skill, когда задача действительно совпадает с его description.

Почему важны AGENTS.override.md и цепочка инструкций

Codex project guidance не сводится к одному файлу ./AGENTS.md.

Эффективная логика:

• Codex идет от project root к текущей директории;
• в каждой директории может быть instruction file;
• AGENTS.override.md имеет приоритет над AGENTS.md в той же директории;
• fallback names могут существовать, если настроены;
• ближние инструкции могут уточнять более общие.

Поэтому architecture-update не должен blindly создавать или редактировать любой AGENTS.md. Он должен:

• предпочитать root instruction file для общей архитектурной ссылки;
• не создавать AGENTS.override.md для обычных обновлений;
• уважать существующий override;
• не трогать fallback-файлы, если проект явно их не использует;
• обновлять nested instruction file только если архитектурное знание относится к subtree.

Это защищает проект от неправильной записи правил в неэффективное место.

Evidence standard: доказательства важнее догадок

architecture-update должен предпочитать факты из:

• changed files;
• git diff;
• существующей документации;
• build/deploy/CI configs;
• package manifests;
• routes;
• entrypoints;
• schema/migration files;
• tests;
• явных пользовательских решений в текущей сессии.

Если факт не доказан, он не должен попадать в основные разделы как истина.

Правильный путь:

Такой подход делает файл честным. Для AI это особенно важно: если документация уверенно говорит неправду, агент будет ошибаться быстрее и увереннее.

Анти-паттерны

Анти-паттерн 1: ARCHITECTURE.md как session log

Плохо:

Хорошо:

Анти-паттерн 2: runbook внутри архитектуры

Плохо:

Хорошо:

Анти-паттерн 3: project skill для слишком общей задачи

Плохо:

.agents/skills/fix-frontend/SKILL.md

Хорошо:

.agents/skills/add-design-system-action-button/SKILL.md

Анти-паттерн 4: выдуманные production facts

Плохо:

Если это не доказано, правильно:

Практический пример: блог

Допустим, в проекте есть блог. Во время работы агент выяснил:

• статьи лежат в content/blog;
• картинки лежат в public/blog;
• markdown парсится через src/lib/blog.ts;
• страницы генерируются как /blog/:slug;
• публикация требует build verification.

Что делает architecture-update?

В ARCHITECTURE.md

Добавляет карту:

В docs/runbooks/publish-blog-post.md

Если публикация статьи повторяемая, создает процедуру:

В .agents/skills/publish-blog-post/SKILL.md

Если агент будет часто сам публиковать статьи, и правила проекта достаточно специфичны, создает project skill:

В AGENTS.md

Добавляет только компактный pointer, если его еще нет:

Практический пример: кнопки

Если в проекте просто изменили одну кнопку, architecture-update ничего не делает.

Если выяснилось, что в проекте есть устойчивый UI workflow:

• все кнопки должны идти через src/components/ui/Button.tsx;
• действия регистрируются в src/features/actions/registry.ts;
• layout rows создаются через ActionRow;
• нужно обновлять stories/tests;
• это повторяется часто,

тогда можно добавить:

В ARCHITECTURE.md:

И, если AI будет часто делать это сам:

.agents/skills/add-design-system-action-button/SKILL.md

Но skill не создается просто потому, что "кнопок много". Он создается только если есть повторяемая, проектно-специфичная процедура.

Почему это долгосрочно экономит токены

Без architecture-update каждая новая сессия заново платит за discovery:

• поиск директорий;
• чтение package/config files;
• понимание routing;
• чтение deployment scripts;
• изучение content pipeline;
• восстановление решений из истории чата.

С architecture-update проект постепенно получает индекс:

• ARCHITECTURE.md говорит, куда смотреть;
• runbook говорит, как выполнить операцию;
• project skill говорит AI, как надежно повторить проектный workflow;
• AGENTS.md кратко направляет агента к нужным слоям;
• new-session читает только релевантное;
• end-session поддерживает память актуальной.

Это не убирает необходимость читать код. Но резко снижает количество бесполезного повторного исследования.

Итоговая логика skill

architecture-update можно описать как строгий маршрутизатор:

1. Найти реальный project root.
2. Проверить существующие memory artifacts.
3. Посмотреть завершенную работу.
4. Вытащить кандидаты на долговечное знание.
5. Отбросить шум.
6. Для каждого оставшегося факта выбрать один слой.
7. Создать или обновить минимальный нужный файл.
8. Проверить ссылки и пути.
9. Неподтвержденное записать в Unknowns.
10. Кратко отчитаться.

Главное не "писать больше документации". Главное — сохранять только ту проектную память, которая уменьшает будущую неопределенность.

Финальная формула

architecture-update нужен не для красоты markdown-файлов. Он нужен, чтобы AI-сессии перестали каждый раз начинать с археологии.

Правильная архитектурная память:

• компактна в always-on контексте;
• подробна в нужном файле;
• доказательна;
• разделяет карту, процедуры и automation;
• честно помечает unknowns;
• обновляется после значимой работы;
• по умолчанию ничего не меняет.

Именно это делает связка:

end-session -> architecture-update -> ARCHITECTURE.md / runbooks / project skills -> new-session

Она превращает разовые открытия в долговечную проектную навигацию.