ARCHITECTURE.md Template — интерактивный шаблон архитектурной документации для AI-агентов

Timaj Williams опубликовал компактный, но тщательно продуманный шаблон ARCHITECTURE.md, который закрывает одну из самых болезненных проблем разработки — отсутствие единой точки входа в проект. Этот документ читают и люди, и AI-агенты: он заточен под то, чтобы новый разработчик или модель могли за минуты понять, как устроена кодовая база, и сразу приступить к работе.

Зачем нужен отдельный шаблон архитектуры

Идея простая. В каждом проекте рано или поздно появляется устная традиция: «вот эти файлы трогать нельзя», «вот так у нас принято», «сервис X общается с Y через Z». Эта традиция живёт в головах у двух-трёх ветеранов и теряется при онбординге. AI-агенты страдают от этого ещё сильнее: у них нет возможности спросить коллегу, и без явного описания архитектуры они принимают решения вслепую.

Timaj формулирует задачу прямо: это системный шаблон для быстрого понимания кодовой базы. Стандартизированный формат даёт два эффекта:

• Онбординг ускоряется. Новый разработчик открывает ARCHITECTURE.md и за полчаса получает карту проекта.
• AI-агенты получают контекст. Claude Code, Codex, Cursor и любые другие ассистенты читают этот файл вместе с кодом и сразу понимают границы системы, контракты и допущения.

Что внутри репозитория

В репозитории четыре файла помимо лицензии:

• README.md — короткое описание шаблона, его назначение и принципы работы с ним.
• architecture.md — сам шаблон, который копируется в целевой проект и заполняется.
• index.html, script.js, style.css — интерактивная веб-версия шаблона, которую удобно просматривать и редактировать через браузер.

Технологический стек минимальный: HTML, CSS и ванильный JavaScript. Никаких сборщиков, фреймворков и зависимостей — это намеренно. Шаблон должен быть таким, чтобы его можно было положить в любой проект, на каком бы стеке тот ни был написан.

Языковая раскладка репозитория: HTML 44.8%, CSS 33.0%, JavaScript 22.2%. Лицензия — Apache-2.0.

Десять разделов шаблона

Структура architecture.md разбита на десять обязательных секций. Каждая отвечает за конкретный класс вопросов.

1. Project Structure

Дерево каталогов с пояснениями к каждой директории. Не нужно описывать каждый файл — достаточно обозначить границы слоёв: backend, frontend, common, docs, scripts, .github. Шаблон уже содержит типичную раскладку для full-stack проекта; её переименовывают под свою кодовую базу.

2. High-Level System Diagram

Текстовое или графическое описание связей между крупными компонентами. Шаблон приводит пример в духе C4-модели уровня System Context: пользователь взаимодействует с фронтендом, фронтенд ходит в несколько backend-сервисов, сервисы работают с базами и внешними API. Цель — зафиксировать главные архитектурные границы.

3. Core Components

Поочерёдное описание каждого значимого компонента: фронтенд, backend-сервисы, воркеры, планировщики. Для каждого указываются имя, ответственность, технологический стек и среда развёртывания.

4. Data Stores

Список всех баз данных и хранилищ: основная БД, аналитическое хранилище, кэш, очереди. По каждому — тип (PostgreSQL, Redis, S3, Kafka), назначение и ключевые коллекции или таблицы.

5. External Integrations

Сторонние сервисы и API: Stripe, SendGrid, Google Maps и т.п. Фиксируется, зачем интеграция нужна и через что она реализована — REST, SDK, gRPC.

6. Deployment & Infrastructure

Облачный провайдер, используемые сервисы, описание CI/CD, инструменты мониторинга и логирования. Эта секция становится контрактом между разработчиками и DevOps: одно место, где зафиксировано, куда и как уезжает код.

7. Security Considerations

Критичные аспекты безопасности: механизмы аутентификации, авторизации, шифрование данных в покое и при передаче, используемые инструменты. Шаблон не диктует конкретные решения, но требует, чтобы они были записаны.

8. Development & Testing Environment

Локальная установка, тестовые фреймворки, линтеры и форматтеры. Здесь же — команды, которые должен знать каждый новый контрибьютор.

9. Future Considerations / Roadmap

Известный технический долг, планируемая миграция, направления развития. Полезно и для людей, и для AI: модель понимает, какие части системы временные и куда движется проект.

10. Project Identification

Имя проекта, URL репозитория, контактное лицо или команда, дата последнего обновления. Мелочь, которая экономит время при эскалации.

Дополнительно шаблон содержит одиннадцатый раздел — Glossary, куда складываются проектные аббревиатуры и термины. Словарь особенно ценен для AI-агентов: модель перестаёт путать омонимы вроде «worktree» (Git) и «worktree» (абстрактный слой проекта).

Зачем это AI-агентам

Когда в проекте есть заполненный ARCHITECTURE.md, агент, открывающий репозиторий впервые, сразу знает:

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

Без такого документа модель будет угадывать. С ним — опираться на явный контракт.

Принципы работы с шаблоном

Timaj формулирует пять правил, и все они одинаково важны:

1. Заполняйте полностью. Пустая секция хуже, чем её отсутствие: читающий тратит время, пытаясь понять, что имелось в виду.
2. Обновляйте регулярно. Архитектура — живой документ. Устаревший ARCHITECTURE.md опаснее, чем его отсутствие: он дезинформирует и людей, и модели.
3. Будьте конкретны. Пишите реальные пути к файлам, имена классов и сервисов. Абстрактные формулировки не помогают ни новичку, ни AI.
4. Добавляйте диаграммы. Визуальное представление системы ускоряет понимание. Шаблон приводит пример текстовой диаграммы, но Mermaid или картинки вполне уместны.
5. Думайте об аудитории. Документ читают и люди, и агенты. Язык должен быть одинаково понятен обеим сторонам: минимум жаргона, максимум конкретики.

Где применять

Автор выделяет пять сценариев:

• Старт нового проекта. Завести ARCHITECTURE.md с первого коммита — дешевле, чем наверстывать через полгода.
• Онбординг команды. Сокращает время, за которое новичок становится продуктивным.
• Интеграция AI-агентов. Прямой контракт между проектом и ассистентом: модель читает файл и сразу понимает границы.
• Code review. Ревьюер сверяет изменение с документом и сразу видит расхождения с заявленной архитектурой.
• Оценка техдолга. Места, где реализация разошлась с описанием, становятся явными.

Лицензия и происхождение

Шаблон опубликован под Apache-2.0 (в файле LICENSE). Это разрешительная лицензия, совместимая с коммерческим использованием. Можно смело копировать шаблон в корпоративные репозитории, дорабатывать под себя и публиковать форки.

Итог

ARCHITECTURE.md Template — это один из тех инструментов, которые стоят дороже, чем кажутся. Шаблон не умеет ничего сам по себе. Но как только команда начинает его вести, исчезает целый класс потерь: новички тратят меньше времени на онбординг, AI-агенты перестают ломать контракты, архитектурные решения перестают теряться в чатах. Если у вас ещё нет единой точки входа в проект — это самый дешёвый способ её завести.

Репозиторий: github.com/timajwilliams/architecture.