Статьи on Михаил Шогин

Экосистема линтеров для AI-агентов: контроль качества, стоимости и безопасности

Tue, 24 Mar 2026 00:00:00 +0000

Проблема

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

Я столкнулся с тремя проблемами одновременно:

Архитектура деградирует - агент пишет код, который работает, но нарушает слоевую архитектуру, создает циклические зависимости и god-классы
Расходы растут - сложный промпт уходит в Opus за $15/1M токенов, хотя Haiku за $0.80 справился бы
Контент не фильтруется - в production-промптах появляется то, что там быть не должно

Каждую из этих проблем можно решить отдельным инструментом. Но когда инструменты работают вместе - они усиливают друг друга.

Пайплайн

Запрос проходит через цепочку линтеров, каждый отвечает за свою область:

seclint - проверяет контент на безопасность (6+/12+/16+/18+)
promptlint - оценивает сложность, выбирает модель
Агент - выполняет задачу на выбранной модели
archlint - проверяет результат на архитектурные нарушения
costlint - записывает стоимость, считает cache hit rate

Если archlint отклоняет результат - задача возвращается на более мощную модель. costlint фиксирует стоимость этой эскалации.

Инструменты

archlint - архитектурный линтер

Сканирует Go-проекты на структурные нарушения.

1

archlint scan --format json ./project/

Что находит:

Нарушения слоев (handler вызывает repository напрямую)
God-классы (>20 методов или >15 зависимостей)
Циклические зависимости
Нарушения Interface Segregation (интерфейсы >5 методов)

Метрики: fan-out, coupling (Ca/Ce), количество компонентов и связей.

GitHub: mshogin/archlint

promptlint - роутер по сложности промптов

Оценивает сложность промпта и выбирает модель. Без LLM, чистые метрики, <10ms.

1
2
3
4
5


echo "Fix typo in README" | promptlint analyze --output-model
# haiku

echo "Design microservices with CQRS" | promptlint analyze --output-model
# opus

Сигналы: длина, количество предложений, доменные ключевые слова, тип действия (fix/create/refactor), наличие кода.

Интеграция с ccproxy - реальный роутинг запросов Claude Code через прокси.

GitHub: mikeshogin/promptlint

costlint - анализ затрат на токены

Считает стоимость, анализирует кэширование, проводит A/B тесты между моделями.

1

costlint report --source telemetry.jsonl

1
2
3
4
5
6
7


Cost Report:
 Total requests: 342
 By model:
 opus: 48 requests, ~$12.60
 sonnet: 195 requests, ~$6.50
 haiku: 99 requests, ~$0.44
 With optimal routing: ~$8.20 (savings: 58%)

Метрики кэширования: cache hit rate, block reuse, content entropy, Jaccard similarity. A/B тесты: сплит трафика 30/30/40, per-group метрики стоимости и качества.

GitHub: mikeshogin/costlint

seclint / promptsec - контент-фильтр

Возрастной рейтинг промптов: 6+, 12+, 16+, 18+.

1
2
3
4
5


echo "Help with math homework" | seclint rate
# {"rating": "6+", "safe": true}

echo "Explain SQL injection for security course" | seclint rate
# {"rating": "16+", "safe": true, "flags": ["security_tools"]}

Учитывает образовательный контекст - объяснение SQL-инъекций для курса по безопасности не блокируется, а получает рейтинг 16+ вместо 18+.

GitHub: mikeshogin/seclint / mikeshogin/promptsec

Общие принципы

Все инструменты следуют одним правилам:

Go - единый стек, единый билд
Без LLM - чистые метрики, regex, keyword matching. <10ms на запрос
CLI + HTTP - каждый инструмент работает как команда и как сервер
JSONL телеметрия - единый формат логов для анализа
Pipeline-friendly - exit codes, stdout, pipes

Числа

На тестовой нагрузке (342 запроса за неделю):

Метрика	До	После
Расход на токены	$19.54	$8.20
Архитектурные нарушения	63	12
Запросы на дорогую модель	100% opus	14% opus
Время роутинга	-	<10ms

Экономия 58% на API без потери качества - дешевые задачи уходят на Haiku, архитектурные задачи остаются на Opus.

Оркестрация

Инструменты работают автономно, но максимальный эффект дают вместе. Для оркестрации используется myhome - daemon-based управление AI-агентами с workflow stages и scheduled tasks.

Связка:

myhome запускает агента
promptlint выбирает модель (pre-route hook)
archlint проверяет результат (quality gate stage)
costlint считает стоимость (telemetry consumer)
seclint фильтрует входящие промпты (pre-filter)

Начать

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


# Установить все
go install github.com/mshogin/archlint@latest
go install github.com/mikeshogin/promptlint/cmd/promptlint@latest
go install github.com/mikeshogin/costlint/cmd/costlint@latest
go install github.com/mikeshogin/seclint/cmd/seclint@latest

# Запустить роутинг
promptlint serve 8090 &
seclint serve 8091 &

# Проверить архитектуру
archlint scan --format json ./my-project/

# Посмотреть затраты
costlint report --source ~/.promptlint/telemetry.jsonl

Ссылки

archlint - архитектурный линтер
promptlint - роутер по сложности
costlint - анализ затрат
seclint / promptsec - контент-фильтр
myhome - оркестрация агентов
ECOSYSTEM.md - карта интеграции

Три блокера, которые мешают техническому лидеру расти

Mon, 16 Mar 2026 00:00:00 +0000

AI меняет IT быстрее, чем мы успеваем адаптироваться. Роли трансформируются. Навыки, за которые платили вчера, обесцениваются сегодня.

Чтобы сохранить уровень жизни - нужно расти. Но рост упирается не в технологии. Не в стек. Не в сертификаты.

Он упирается в мышление.

Сильные специалисты застревают. Не потому что не хватает знаний. А потому что есть внутренние блокеры, которые сложно увидеть самому.

Я работаю с архитектурой систем больше пятнадцати лет. И последние несколько лет замечаю: самые серьезные баги - не в коде. Они в головах людей, которые этот код пишут и управляют теми, кто пишет.

Вот три паттерна, которые я вижу чаще всего. В других. И в себе.

Блокер 1: Защита территории

У каждого лидера есть зона ответственности. И любой вход в нее воспринимается как атака. Это инстинкт - как хищник обходит свои границы.

Как это выглядит

Представь ситуацию. Ты архитектор. Системный аналитик из твоей команды начинает принимать архитектурные решения самостоятельно. Делает это неплохо, но без согласования с тобой. Ты видишь результат - решения рабочие, но ощущаешь внутри раздражение, которое сложно объяснить рационально.

На совещании ты начинаешь давить. Не потому что решение плохое - а потому что оно принято без тебя. Формально ты говоришь про качество и процессы. Реально - защищаешь территорию.

Другой пример. Тимлид замечает, что senior в команде начинает брать на себя архитектурные вопросы. Вместо того чтобы дать пространство и помочь вырасти, тимлид усиливает контроль. Больше ревью. Больше согласований. Больше вопросов в стиле “а ты подумал про…”. Формально - забота о качестве. Реально - страх стать ненужным.

Почему это блокер

Проблема не в защите. Защищать границы - нормально.

Проблема в том, КАК ты защищаешь. Из уверенности в своих силах - или из страха, что отберут? Первое - лидерство. Второе - агрессия, которую люди чувствуют. И уходят.

Если провести аналогию с системами: это как микросервис, который вместо того чтобы предоставлять API для взаимодействия, закрывает все порты и отвечает 403 на любой запрос. Технически он работает. Но система вокруг него деградирует.

Навык

Различать реальную угрозу и фантомную. Один вопрос себе: “я сейчас защищаю качество - или защищаю свое эго?”

Блокер 2: Жажда признания

На самом деле это про обратную связь.

Как это выглядит

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

И тишина. Никто не подошел и не сказал “классная работа”. Руководитель молчит. Команда приняла результат как должное.

В этой тишине мозг начинает додумывать: “наверное, я плохо работаю”. Или хуже: “наверное, они не ценят то, что я делаю”.

Знакомая история: архитектор выстроил процесс API-review для системных аналитиков. Качество спецификаций выросло. Количество багов на этапе интеграции упало. Но руководитель ни разу не сказал “хорошая работа”. И в какой-то момент архитектор начал задаваться вопросом - а стоило ли вообще тратить на это время.

Еще пример. Senior-разработчик потратил месяц на рефакторинг критического модуля. Код стал чище, тесты - надежнее, время деплоя сократилось вдвое. На ретро об этом даже не упомянули. Senior начал демотивироваться - не потому что работа была бессмысленной, а потому что никто не заметил.

Почему это блокер

Во взрослой жизни никто не придет и не скажет “ты молодец”. Это делали родители. А на работе - тишина. И в этой тишине мозг начинает додумывать.

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

Навык

Либо научиться просить обратную связь - это не слабость, это зрелость. Либо выстроить внутреннюю опору, которая не зависит от чужих слов.

Практически: завести свой лог достижений. Раз в неделю записывать, что сделал и какой эффект это дало. Через полгода у тебя будет объективная картина - независимо от того, заметил руководитель или нет.

Блокер 3: Опыт как ловушка

Большой опыт создает иллюзию: “я больше знаю - мне должны”.

Как это выглядит

Совещание. Ты - самый опытный в комнате. Junior предлагает решение. Ты видишь в нем проблемы. И вместо того чтобы задать вопрос - “а что будет при нагрузке 10x?” - ты говоришь: “нет, так не делают, я десять лет занимаюсь этим и знаю”.

Формально ты прав. Решение действительно может не выдержать нагрузку. Но ты убил две вещи: инициативу junior-а и возможность для команды научиться думать самостоятельно.

Другой пример. Опытный тимлид приходит в новую команду. У него за плечами три успешных проекта с определенным стеком. Команда использует другой подход. Вместо того чтобы разобраться, почему выбран именно этот подход, тимлид начинает продавливать свой. Не потому что он лучше - а потому что знакомый. И потому что признать чужой подход = признать, что твой опыт не универсален.

Я сам ловлю себя на этом. Иногда давлю опытом вместо того чтобы слушать. И каждый раз, когда ловлю себя на этом, задаю вопрос: я сейчас учу - или доказываю?

Почему это блокер

Мир трансформируется. Старые шаблоны рушатся. В эпоху AI вчерашний эксперт сегодня учится заново. Опыт - ценность, но не валюта для обмена на покорность.

Если как систему: это legacy-сервис с hardcoded конфигурацией. Когда-то он работал отлично. Но мир вокруг изменился, а он все еще ожидает запросы в старом формате. И вместо того чтобы адаптировать API - требует, чтобы все остальные адаптировались под него.

Навык

Относиться к коллегам как к равным. Независимо от разницы в опыте. Это не значит игнорировать свой опыт - это значит делиться им через вопросы, а не через давление.

Три блокера. Три навыка. Ни один - про технологии

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

Как в любом проекте: чтобы увидеть архитектурные проблемы, нужен взгляд снаружи. Тот, кто внутри системы, видит отдельные симптомы. Тот, кто снаружи - видит паттерн.

Лидерство начинается не с архитектуры систем, а с архитектуры мышления. И если ты чувствуешь, что застрял - возможно, дело не в том, что ты мало знаешь. А в том, что пора посмотреть на свое мышление как на систему и провести ему честный аудит.

Фаулер про LLM и разработчиков: cognitive debt, supervisory programming и кто на самом деле под ударом

Fri, 13 Feb 2026 00:00:00 +0000

Мартин Фаулер опубликовал заметки с встречи senior-разработчиков, посвященной LLM. Не очередной хайп про “AI заменит всех” - а трезвый разбор от людей, которые пишут код десятилетиями.

Несколько тезисов зацепили настолько, что захотелось разобрать их подробнее. С примерами из собственной практики.

Mid-level под ударом, а не джуны

Обычно все переживают за junior-разработчиков: их-то заменят первыми. Фаулер с группой пришли к обратному выводу.

Джуны адаптивны. Они росли с LLM, умеют ими пользоваться, открыты к новому. Сеньоры понимают архитектуру, видят систему целиком, эффективно управляют агентами - примерно как управляют джунами.

А mid-level? Они сформировались без LLM, но еще не набрали достаточно опыта, чтобы эффективно ими управлять. Застряли между двумя мирами.

На практике я вижу это так: mid-level разработчик умеет писать код. Хорошо умеет. Но когда LLM генерирует код быстрее - “умение писать код” перестает быть конкурентным преимуществом. А понимание “зачем этот код нужен”, “как он вписывается в систему”, “какие trade-offs мы принимаем” - это уже территория сеньоров.

Один из участников рассказал показательную историю: сеньоры в их компании были резко против LLM. Но когда их заставили поработать руками - треть моментально стала pro-LLM. Практический опыт важнее теоретических страхов. Как пошутили на встрече, некоторые негативные мнения о LLM “остались в январе”.

Что делать mid-level

Если ты mid-level - у тебя есть окно. Не в том, чтобы учиться промптить. А в том, чтобы быстрее набирать архитектурное мышление: понимание систем, trade-offs, бизнес-контекста. То, что LLM пока делает плохо.

Cognitive debt опаснее technical debt

Это, на мой взгляд, самый ценный тезис. Фаулер ссылается на исследование Margaret-Anne Storey и проводит параллель с technical debt.

Её кейс: студенческие команды строили продукт, генерируя код с помощью LLM. К 7-8 неделе одна команда уперлась в стену - любое изменение ломало что-то неожиданное. Сначала обвинили технический долг. Но реальная проблема была в другом: никто в команде не мог объяснить, почему были приняты те или иные решения. Shared understanding - общее понимание системы - фрагментировалось и исчезло.

Фаулер разделяет это на два слоя:

Cruft (хлам в коде) -> в когнитивной сфере это ignorance (невежество) - незнание кода и домена
Debt (долг как метафора стоимости) -> либо платишь “проценты” (каждое изменение дороже), либо “гасишь тело” (инвестируешь в понимание)

Это точное попадание в то, что я вижу при приемке проектов. Не раз сталкивался с ситуацией: код написан грамотно, тесты есть, линтеры проходят - но никто не может объяснить, почему выбрана такая декомпозиция сервисов. Или зачем нужен этот промежуточный слой. Документация говорит “что”, но не говорит “зачем”.

С LLM-агентами cognitive debt будет масштабироваться: код генерируется быстрее, чем команда успевает его осмыслить. Скорость создания кода перестает быть ограничителем. Ограничителем становится скорость понимания.

Как с этим работать

Несколько практик, которые помогают:

ADR (Architecture Decision Records) - фиксируем не “что решили”, а “почему решили и какие варианты отвергли”
Коучинговые вопросы на ревью - вместо “используй Strategy pattern” спрашивать “какие варианты ты рассмотрел? какие trade-offs?”
Обязательный контекст в PR - не просто diff, а “зачем” это изменение нужно

Если LLM генерирует код - пусть генерирует и ADR к нему. Хотя бы черновик для ревью.

DevEx и Agent Experience - это круг

Laura Tacho сказала фразу, которая заслуживает стать мемом:

The Venn Diagram of Developer Experience and Agent Experience is a circle

Всё, за что годами боролись в developer experience - гладкий тулинг, понятная документация, чистая модульность, осмысленные имена - оказывается, помогает и LLM-агентам. Хорошая модульность и descriptive naming так же полезны для трансформера, как и для “более мягких нейронных сетей” (мозгов).

И горькая ирония: менеджмент готов инвестировать в “smooth path для LLM”, но не готов был делать это для людей. Экзекьютивам не жалко денег на роботов, но жалко на разработчиков.

Из моего опыта: чистая архитектура с явными зависимостями, маленькими интерфейсами и четкими слоями - это ровно то, что позволяет LLM-агенту эффективно работать с кодобазой. Когда я настраивал Claude Code для работы со своими проектами, разница была заметна сразу: в проекте с чистой архитектурой агент находит нужный контекст за секунды. В проекте-монолите с неявными зависимостями - путается, галлюцинирует, предлагает изменения не в тех файлах.

Вывод неутешительный и простой: если ваша кодобаза - хаос для людей, она будет хаосом и для агентов. Инвестиции в DevEx теперь имеют двойной ROI.

Supervisory programming и менеджерское выгорание

Камилла Фурнье заметила:

The part of “everyone becomes a manager” in AI that I didn’t really think about until now was the mental fatigue of context switching

Тренд “один программист управляет несколькими агентами” несет с собой ровно ту же болезнь, от которой годами страдают менеджеры: усталость от переключения контекста. Держать в голове 5 параллельных задач, ревьюить результаты из разных контекстов, ловить ошибки в коде, который ты не писал - это менеджмент, а не программирование.

Фаулер осторожно предполагает, что два человека + агенты могут быть эффективнее, чем один человек + много агентов. Парное программирование нового формата: два мозга ловят ошибки “джинна” лучше, чем один.

Мне эта мысль близка. В коучинге есть концепция: сам себе коучем быть нельзя, нужен внешний наблюдатель. С кодом похоже - второй человек видит то, что ты пропустил. А когда агенты генерируют код быстрее, чем один человек может ревьюить - второй мозг не роскошь, а необходимость.

Workload creep

Фаулер также цитирует исследование из Harvard Business Review: в компании на 200 человек после внедрения AI сотрудники стали работать быстрее, брать больше задач, работать больше часов - часто без просьбы. Звучит как мечта менеджера. Но за первоначальным всплеском приходит: cognitive fatigue, выгорание, ухудшение качества решений.

Это классический паттерн. Новый инструмент дает эйфорию -> берешь больше -> не замечаешь, как нагрузка выросла -> burnout.

Размер команд

Уменьшатся ли команды? Фаулер склоняется к “нет”. Two-pizza teams (5-8 человек) останутся примерно того же размера - но будут делать значительно больше. Есть что-то фундаментальное в размере команды, что балансирует выгоды сотрудничества с издержками координации. LLM не едят пиццу, но они и не добавляют в team dynamics.

Будущее IDE

Отдельная тема - будущее IDE. LLM не заменяют IDE, а встраиваются в них. Переименовать функцию через LLM - это как забивать гвоздь микроскопом. Но LLM может оркестрировать инструменты IDE: увидеть, что “person” нужно переименовать в “contact” во всех контекстах (функции, поля, документация, тесты), и использовать детерминистические рефакторинги IDE для каждого из них.

Мне как пользователю Emacs это особенно резонирует. IDE - это мощный инструмент, но мало кто использует его на полную. LLM может стать тем слоем, который знает возможности IDE лучше пользователя и подсказывает, когда использовать LLM, когда - детерминистический рефакторинг, а когда - их комбинацию.

Итого

Главные мысли из текста Фаулера:

Mid-level под ударом - не джуны, как все думали. Окно для роста: быстрее набирать архитектурное мышление
Cognitive debt > technical debt - с LLM код генерируется быстрее, чем осмысляется. Ограничитель теперь - понимание, а не написание
DevEx = Agent Experience - инвестиции в чистую архитектуру дают двойной ROI
Supervisory programming = менеджерское выгорание - context switching утомляет. Пара людей + агенты может быть лучше одиночки + много агентов
Workload creep - эйфория от AI -> перегрузка -> burnout. Классика

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

А ты замечаешь cognitive debt в своих проектах?

Архитектура памяти для AI-агентов: как я научил Claude Code помнить

Wed, 11 Feb 2026 00:00:00 +0000

Боль: агент с амнезией

Каждый, кто работает с AI-агентами, знает ощущение: ты объяснил контекст проекта, показал структуру, обсудил решения - а в следующей сессии агент всё забыл. Опять здрасьте. Опять “расскажите про ваш проект”.

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

У меня 12+ активных контекстов: рабочие проекты (Wildberries), личные проекты (aitrader, archlint), блог, коучинговая практика, обучение, целеполагание. Переключение между ними без памяти превращалось в ритуал: 5-10 минут на “загрузку контекста” в начале каждой сессии.

Стало ясно: нужна архитектура памяти.

Как устроена человеческая память

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

flowchart TD A["Входящие данные"] --> B["Рабочая память\n(Short-Term)\nАктивные задачи,\nтекущий контекст"] B --> C{"Фильтр ценности\n(еженедельный ревью)"} C -->|"Ценно"| D["Долговременная память\n(Long-Term)\nПаттерны, принципы, уроки"] C -->|"Обработано"| E["Архив\n(забыто, но доступно)"]

У людей так же:

Рабочая память (Short-Term) - то, с чем работаешь прямо сейчас. Ограничена: ~7 элементов одновременно. Через 3-6 месяцев без обращения - забывается.
Долговременная память (Long-Term) - дистиллированные знания. Не “что я делал во вторник”, а “какой паттерн я увидел за три месяца работы”.
Архив - не удалено, но не на поверхности. Доступно при целенаправленном поиске.

Ключевой момент: переход из Short-Term в Long-Term - не автоматический. Нужна осознанная обработка. В коучинге это рефлексия. В моей системе - еженедельный ревью.

Архитектура решения

Три уровня памяти

Я реализовал три уровня, зеркалирующих человеческую модель:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


~/my/org-roam/
+-- Short-Term-Memory/ # Рабочая память (3-6 месяцев)
| +-- Wildberries/ # Рабочий контекст
| +-- Coaching/ # Коучинговые сессии
| +-- daily/ # Ежедневные заметки
| +-- todos.md # Задачи
|
+-- Long-Term-Memory/ # Долговременная память
| +-- Coaching/ # Методики, паттерны, кейсы
| +-- Architecture/ # Архитектурные решения
| +-- Posts/ # Публикации
| +-- Personal/ # Личные принципы
|
+-- Archive/ # Архив (по месяцам)
 +-- 2026/
 +-- 01-January/
 +-- 02-February/

Short-Term - inbox для всего нового. Сырые заметки, текущие задачи, эксперименты. Максимум 50 активных файлов. Если больше - пора делать ревью.

Long-Term - база знаний. Сюда попадает только то, что прошло фильтр ценности:

Переиспользуемость (применимо 3+ раз)
Обучающая ценность (ага-момент, важная ошибка)
Референсная ценность (пример для копирования)

Archive - завершенные проекты, обработанные заметки. Не удалено, но убрано с глаз.

Контексты: переключение за секунду

Вторая проблема - переключение между проектами. Решение: система контекстов.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


{
 "contexts": {
 "coaching": {
 "name": "coaching",
 "description": "Коучинговые сессии и практика развития",
 "directory": "~/my/coaching",
 "memory": {
 "short_term": "~/my/org-roam/Short-Term-Memory/Coaching",
 "long_term": "~/my/org-roam/Long-Term-Memory/Coaching"
 }
 },
 "archlint": {
 "name": "archlint",
 "description": "ArchLint - линтер архитектуры Go проектов",
 "directory": "~/my/archlint",
 "memory": {
 "short_term": null,
 "long_term": null
 }
 }
 }
}

Каждый контекст знает:

directory - рабочая директория проекта
memory.short_term - где хранить текущие заметки
memory.long_term - где хранить дистиллированные знания

Переключение: одна команда /w coaching - и агент знает где он, что помнить, какие файлы читать.

Индекс активностей: навигация по всему

Контексты решают проблему “где я”. Но остается вопрос: “где искать информацию по теме X?”. Для этого - глобальный индекс активностей.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


### Коучинг / Практика

- Keywords: сессия, клиент, практика, рефлексия
- Файлы:
 - Практика: ~/my/org-roam/Long-Term-Memory/Coaching/03-Практика/
 - Гайды сессий: ~/my/org-roam/Long-Term-Memory/Coaching/session-guides/INDEX.md

### Здоровье и психология

- Keywords: психолог, здоровье, границы, стыд
- Файлы:
 - Темы: ~/my/org-roam/Long-Term-Memory/Темы для психолога.md
- Связанные активности: Коучинг / Запросы для проработки

Принцип работы:

flowchart TD A["Промпт пользователя"] --> B["Поиск по keywords\nв memory-index.md"] B --> C{"Найдена\nактивность?"} C -->|"Да"| D["Работай в её контексте"] C -->|"Нет"| E["Спроси пользователя,\nпредложи варианты"]

Кросс-контекстный поиск: связи между контекстами

Самая интересная архитектурная задача. Информация часто пересекает границы контекстов.

Пример: тема “границы” может всплыть в коучинге (запрос клиента), в психологии (тема для терапии), в рабочем контексте (обратная связь коллеге). Как не потерять связь?

Решение: кросс-ссылки на уровне глобального индекса, а не дублирование информации между контекстными индексами.

flowchart TD G["memory-index.md\n(глобальный индекс)"] --> C1["Coaching\nINDEX.md"] G --> C2["Здоровье\n(файлы)"] G --> C3["Работа\nINDEX.md"] G --> C4["..."] C1 -.-|"кросс-ссылка"| C2 C2 -.-|"кросс-ссылка"| C3 style G fill:#0f3460,color:#fff style C1 fill:#533483,color:#fff style C2 fill:#533483,color:#fff style C3 fill:#533483,color:#fff style C4 fill:#333,color:#999

Правило: каждый контекстный индекс отвечает только за свой контекст. Связь между контекстами - через поле “Связанные активности” в глобальном индексе.

1
2
3
4
5
6


## Кросс-ссылки между активностями

| Активность A | Активность B | Связь |
|--------------------------|------------------------|-------------------------------------|
| Коучинг / Запросы | Здоровье и психология | Запрос #11 = Тема #2 (границы) |
| Семья | Коучинг / Запросы | Запрос #3 (темы с супругой) |

Антипаттерн: дублировать ссылки на “Темы для психолога” внутри Coaching/INDEX.md. Это нарушает single responsibility - индекс коучинга не должен знать про психологию. Связь - только через глобальный уровень.

Жизненный цикл знаний

Данные без обработки - мусор. Система памяти работает, только если есть процесс трансформации.

flowchart LR subgraph ST ["Short-Term (сырые данные)"] A1["Заметки по сессии\nс клиентом X"] A2["Тикеты проекта\nархитектуры"] A3["Исследование\nTarjan алгоритма"] end subgraph LT ["Long-Term (знания)"] B1["Паттерн: Работа с\nпрокрастинацией\nчерез ценности"] B2["ADR-0042: Выбор\nмежду монолитом\nи микросервисами"] B3["Библиотека\nалгоритмов\nпоиска циклов"] end A1 -->|"трансформация"| B1 A2 -->|"трансформация"| B2 A3 -->|"трансформация"| B3

Критерии перехода в Long-Term

Не всё заслуживает долговременной памяти. Четыре фильтра:

Переиспользуемость - применимо 3+ раз (методики, шаблоны, чек-листы)
Обучающая ценность - ага-момент, важная ошибка, смена парадигмы
Референсная ценность - пример для копирования (код, кейс, формат)
Паттерн - повторяющаяся проблема + решение

Всё остальное - одноразовые заметки, устаревшие TODO, рутинные логи - удаляется или уходит в архив.

Еженедельный ревью

Раз в неделю - 30-40 минут на обработку Short-Term:

Просмотреть файлы за неделю
Выделить ценное для Long-Term
Трансформировать: сырые данные -> структурированные знания
Архивировать обработанное
Удалить мусор

Метрики здоровой системы:

Short-Term: 30-50 активных файлов
Long-Term: +2-5 новых записей в неделю
Archive: регулярное пополнение

Параллель с коучингом

Когда я проектировал эту систему, я заметил параллели с тем, что изучаю в коучинге.

Short-Term = Рабочая осознанность

Когда человек разбирается в сложной ситуации, он сначала выгружает всё, что на поверхности: факты, эмоции, людей, обстоятельства. Это рабочая память - хаотичная, перегруженная, но актуальная. Short-Term Memory в моей системе работает так же: собирает всё, что сейчас активно, без фильтрации.

Long-Term = Мудрость через рефлексию

Long-Term - это не “запомнить всё”. Это “понять, что важно”. Лучшие инсайты приходят не в момент обсуждения, а позже - когда человек рефлексирует и видит паттерн. Еженедельный ревью - это та самая рефлексия, только для базы знаний.

Кросс-контекст = Системное мышление

Проблема редко живет в одном контексте. Одна и та же тема может всплыть и на работе, и в личных проектах, и в обучении. Кросс-ссылки в системе памяти - это способ видеть одну тему с разных сторон, расширить перспективу.

Architect of Thinking

Изучая коучинг, я разработал авторский фреймворк на стыке архитектуры и работы с мышлением - Architect of Thinking. Формула:

Контекст -> Цель -> Карта -> Узел -> Решение -> Шаг

Это ровно то, как архитектор работает с системой: сначала изучи (контекст), определи цель, построй карту, найди bottleneck (узел), спроектируй решение, сделай первый шаг. Тот же подход - к человеческим задачам.

Результаты

До системы памяти:

5-10 минут на “загрузку контекста” каждую сессию
Потеря решений между сессиями
Дублирование работы
Невозможность связать темы между контекстами

После:

Переключение контекста за 1 команду
Знания накапливаются и структурируются
Связи между контекстами через кросс-ссылки
Еженедельный ревью превращает данные в знания

Что дальше

Система живая - она развивается вместе с моими проектами. Следующие шаги:

Автоматизация ревью (AI-помощник для еженедельной обработки Short-Term)
Семантический поиск по Long-Term Memory
Версионирование знаний (как знания меняются со временем)

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

Исходный код и конфигурации описаны для Claude Code (Anthropic CLI). Подход применим к любому AI-агенту с файловой системой.

Spec-Driven Development: контроль AI-кодогенерации

Tue, 09 Dec 2025 00:00:00 +0000

В этой статье

Проблема: большие MR и размытые требования
Идея: спецификации как контракт
Метод: структура и размеры спецификаций
Что делает AI: редактор и исполнитель
Эксперимент: 85% воспроизводимости за 20 минут
Ограничения и Итоги

Проблема

Большие MR

4000 строк в одном MR. Три часа на ревью, 12 замечаний, исправления - ещё 800 строк. На четвёртом заходе я закрыл вкладку и понял: проблема не в коде, а в том, что никто не знал, что именно нужно было написать.

Если ты работаешь с большими кодовыми базами, ситуация знакомая. Большие MR - симптом. Когда непонятно, что именно нужно сделать, разработчик пишет больше кода, чем требуется. Добавляет на всякий случай. Покрывает сценарии, которые никто не просил. MR растёт не потому что задача большая, а потому что границы размыты.

Другая причина - иллюзия, что проще сделать всё в одной задаче, чем декомпозировать. Кажется, что разбиение создаёт лишнюю работу. На практике монолитный MR на 4000 строк никто не может нормально проверить, и баги просачиваются в продакшн.

AI-кодогенерация

С AI эта проблема становится критичнее. Агент пишет код быстро, но если требования размыты - генерирует то же самое: много кода на всякий случай.

Я пользуюсь AI ежедневно. Claude Code - основной инструмент, в который можно подключить разные модели: Anthropic, DeepSeek, GPT-семейство, локальные через Ollama. И в какой-то момент заметил закономерность: чем точнее формулирую задачу, тем лучше результат. Промпты становились всё более структурированными - простые инструкции, потом шаблоны, потом что-то похожее на техническое задание.

Где проблема? Сначала я думал, что ленюсь давать AI детальные инструкции. Потом решил, что AI Agent собирает недостаточный контекст - нужен RAG или что-то подобное. В итоге понял, что проблема в обоих местах: создавать полные инструкции кажется оверкилом, а как помочь агенту собрать нужный контекст - непонятно.

Но главное - нечего проверять. Нет артефакта, на который можно указать и сказать: здесь написано одно, а сделано другое.

Идея

Идея не новая - в индустрии давно говорят о spec-first подходе. Я долго хотел попробовать и наконец решил проверить.

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

AI Agent будет генерировать более предсказуемый код
Результат можно будет валидировать против спецификации
Архитектура останется контролируемой

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

Метод

Я решил проверить гипотезу на реальном проекте - инструменте для построения архитектурных графов из Go кода. Правило простое: ни одной строчки кода без спецификации.

Первая спецификация - создать пустой проект на Go со стандартным layout. Вторая - модель графа. Третья - анализатор Go кода. За несколько дней накопилось 10 завершённых спецификаций.

Структура хранения

Kanban-подобная организация через файловую систему:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


specs/
├── todo/ # очередь задач
│ ├── 0010-feature-x.md
│ └── 0020-feature-y.md
├── inprogress/ # в работе (максимум одна - WIP limit)
│ └── 0005-current.md
└── done/ # выполнено
 ├── 0001-init-project.md
 ├── 0003-data-model.md
 └── 0004-go-analyzer.md

Приоритизация через числовой префикс: меньше число - выше приоритет. Переход между состояниями - перемещение файла между директориями.

graph LR TODO["todo/"] --> INPROGRESS["inprogress/"] INPROGRESS --> DONE["done/"]

Размеры спецификаций

Классификация по времени на написание спецификации (T-shirt sizing):

S (Small) - до 10 минут
M (Medium) - 10-20 минут
L (Large) - больше 20 минут

Размер определяет глубину проработки. S-задача: Problem Statement и 5 Acceptance Criteria. L-задача: полные UML/C4 диаграммы, детальные Requirements, 15+ критериев приёмки. Корреляция между размером спецификации и предсказуемостью результата - прямая.

Если начинаешь с нуля - попробуй с S-спецификации. Это минимальные затраты на эксперимент.

Пример S-спецификации: инициализация проекта


# Spec 0001: Initialize Standard Golang Project Layout
**Metadata:**
- Priority: 0001
- Status: Done
- Effort: S
## Overview
### Problem Statement
Необходимо создать базовую структуру Go проекта для инструмента
archlint согласно стандартным практикам разработки.
### Solution Summary
Инициализировать Go module и создать минимальную структуру проекта.
## Requirements
### R1: Go Module Initialization
- Инициализировать Go module с именем github.com/mshogin/archlint
### R2: Minimal Directory Structure
- Создать cmd/archlint/ для точки входа
- Создать internal/ для приватного кода
- Создать pkg/ для публичных библиотек
## Acceptance Criteria
- [x] AC1: go.mod создан с module path github.com/mshogin/archlint
- [x] AC2: cmd/archlint/main.go существует и компилируется
- [x] AC3: Директории internal/ и pkg/ существуют

Минимум деталей, максимум конкретики. AI получает чёткие границы задачи.

Пример M-спецификации: команда collect

Средние задачи требуют диаграмм. Я экспериментировал с Sequence-диаграммами - отправлял их агенту вместе с требованиями. Заметил, что по ним AI Agent выдаёт в целом то, что ожидается.


# Spec 0006: Implement Collect Command
**Metadata:**
- Priority: 0006
- Status: Done
- Effort: M
## Overview
### Problem Statement
Необходимо реализовать команду collect для сбора архитектуры
из исходного кода и сохранения графа в YAML файл.
### Solution Summary
Создать подкоманду collect, которая использует GoAnalyzer
для анализа кода и сохраняет результат в YAML формате.
## Architecture
### Sequence Flow (PlantUML)
@startuml
title Sequence: Collect Command
actor User
participant "collectCmd" as CC
participant "GoAnalyzer" as GA
participant "saveGraph" as SG
User -> CC: archlint collect . -o arch.yaml
CC -> GA: Analyze(dir)
GA --> CC: *Graph
CC -> SG: saveGraph(graph)
SG --> CC: nil
CC --> User: "Graph saved to arch.yaml"
@enduml
## Requirements
### R1: Command Definition
var collectCmd = &cobra.Command{
Use: "collect [директория]",
Short: "Сбор архитектуры из исходного кода",
Args: cobra.ExactArgs(1),
RunE: runCollect,
}
### R2: Flags
-o, --output: выходной YAML файл (default: architecture.yaml)
-l, --language: язык программирования (default: go)
## Acceptance Criteria
- [x] AC1: Команда принимает директорию как аргумент
- [x] AC2: Флаги -o и -l работают
- [x] AC3: Результат сохраняется в YAML
- [x] AC4: Выводится статистика по компонентам

Sequence-диаграмма определяет порядок вызовов. AI следует ей буквально.

Пример L-спецификации: анализатор Go кода

Большие задачи требуют нескольких диаграмм - Data Model и Sequence:


# Spec 0004: Implement Go Code Analyzer
**Metadata:**
- Priority: 0004
- Status: Done
- Effort: L
## Overview
### Problem Statement
Необходимо реализовать анализатор Go кода, который парсит исходный код
с помощью AST и строит граф зависимостей между компонентами.
### Solution Summary
Создать GoAnalyzer в пакете internal/analyzer, который использует
go/ast и go/parser для анализа Go файлов и построения графа.
## Architecture
### Data Model
@startuml
class GoAnalyzer {
-packages: map[string]*PackageInfo
-types: map[string]*TypeInfo
-functions: map[string]*FunctionInfo
-nodes: []model.Node
-edges: []model.Edge
--
+NewGoAnalyzer() *GoAnalyzer
+Analyze(dir string) (*model.Graph, error)
-parseFile(filename string) error
-buildGraph()
}
class PackageInfo {
+Name: string
+Path: string
+Imports: []string
}
class TypeInfo {
+Name: string
+Package: string
+Kind: string
+Fields: []FieldInfo
}
GoAnalyzer "1" *-- "*" PackageInfo
GoAnalyzer "1" *-- "*" TypeInfo
@enduml
### Sequence Diagram
@startuml
title Sequence: Code Analysis
actor User
participant "GoAnalyzer" as GA
participant "go/parser" as GP
participant "buildGraph" as BG
User -> GA: Analyze(dir)
loop For each .go file
GA -> GP: ParseFile(filename)
GP --> GA: *ast.File
GA -> GA: Extract packages, types, functions
end
GA -> BG: buildGraph()
BG --> GA: *Graph
GA --> User: *Graph, nil
@enduml
## Requirements
### R1: AST Parsing
- Парсить все .go файлы в директории
- Извлекать packages, types, functions, methods
### R2: Graph Building
- Создавать Node для каждого компонента
- Создавать Edge для каждой связи (import, calls, uses)
### R3: External Dependencies
- Идентифицировать внешние зависимости
- Помечать их как entity: external
## Acceptance Criteria
- [x] AC1: Анализатор корректно парсит Go код
- [x] AC2: Все типы компонентов извлекаются
- [x] AC3: Все типы связей определяются
- [x] AC4: Внешние зависимости идентифицируются
- [x] AC5: Граф сериализуется в YAML

Для L-задач несколько диаграмм - необходимость. Data Model, Sequence, Component - вместе они задают архитектуру приложения и управляют зависимостями между компонентами.

Что делает AI

AI ускоряет работу, но архитектуру я не делегирую: решения фиксируются в спецификации, проходят ревью и проверяются валидаторами. Однако решения редко рождаются из воздуха: я приношу первичные варианты и ограничения, агент предлагает альтернативы и подсвечивает слепые зоны. Это влияет на ход мысли, и я это осознаю. Финальное “да/нет” и ответственность лежит на мне.

У агента две зоны ответственности.

Specification Editor Я диктую голосом сырой поток мыслей (диктую быстрее, чем печатаю). Агент приводит его к моему шаблону спецификации: раскладывает по секциям, уточняет недосказанное, формулирует требования и критерии приемки так, чтобы их можно было проверить. После этого я ревьюю и фиксирую спецификацию как исходный контракт.
Implementation Executor Когда спецификация согласована, я отдаю её агенту на реализацию. Агент пишет код по спецификации, а я проверяю результат: ревью, валидация, итерации до тех пор, пока архитектура не станет чистой и предсказуемой.

graph LR A["Идеи/варианты (я)"] --> B["AI дополняет и формализует"] B --> C["Спецификация"] C --> D["Ревью и решения (я)"] D --> E["Реализация (AI)"]

Эксперимент

За несколько дней - 10 завершённых спецификаций и работающий проект. Код соответствует архитектуре из диаграмм.

Чтобы проверить, насколько спецификации самодостаточны, я провёл эксперимент: дал Claude Code пустую директорию и 10 спецификаций из archlint - без доступа к исходному коду. Задача: воссоздать проект с нуля.

Результат за 20 минут:

85.5% успешность воспроизведения
100% структурная идентичность (директории, файлы, типы)
23 мутации в деталях реализации

Структура проекта воспроизведена полностью. Все acceptance criteria из спецификаций выполнены. Проект компилируется и проходит тесты.

Мутации возникли там, где спецификации описывали что делать, но не как. Критический пример: алгоритм построения sequence-диаграммы был реализован иначе - функционально эквивалентно, но с другой логикой обхода стека вызовов. Ещё одна категория мутаций - стилистические: язык комментариев, порядок функций в файлах, именование переменных.

Вывод для улучшения спецификаций: для критических алгоритмов нужен псевдокод или конкретные примеры входов/выходов. Спецификация что + как даёт более точное воспроизведение, чем только что.

Полный отчёт с каталогом мутаций: github.com/mshogin/archlint-reproduction

Идемпотентность спецификаций

Чтобы спецификации оставались воспроизводимыми, все изменения должны проходить через них. Никаких доработок в режиме copilot, никаких чатов с “поправь вот это”. Каждое изменение - обновление спецификации, затем реализация.

Это основной вызов. Хочется быстро поправить баг в диалоге, а не возвращаться к спеке. Но каждая такая правка - потеря воспроизводимости.

Trade-off очевиден:

Нужен результат здесь и сейчас - режим copilot быстрее
Нужна воспроизводимость - только через спецификации

Выбор зависит от контекста. Прототип или эксперимент - copilot. Продуктовый код с долгим жизненным циклом - спецификации.

Ограничения

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

Цена: время на написание спецификаций, их ревью и итерации после валидации. Если относиться к спекам формально, всё скатывается обратно в хаос. Честно спроси себя: готов ли ты тратить 10-30 минут на спецификацию, чтобы агент реализовал её за 5-20 минут?

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

Я думаю, что подход работает хорошо там, где есть поставленный, сформированный и рабочий процесс. В процессах с фокусом на дисциплину, на понятные зоны ответственности, ревью, критерии готовности. Можно смотреть на этот процесс как на конвейер, доставляющий ПО 24/7.

Итоги

Гипотеза подтвердилась:

AI генерирует более предсказуемый код - да, при наличии диаграмм
Результат можно валидировать - да, 85.5% воспроизводимость
Архитектура остаётся контролируемой - да, 100% структурная идентичность

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

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

Шаблоны и примеры: github.com/mshogin/archlint

Если пробуешь spec-driven подход или уже используешь - расскажи в комментариях, что работает, а что нет. Пишу о практике AI-кодогенерации и архитектуре в Telegram: @MikeShogin

Структурная и поведенческая архитектура: графовый подход к контролю сложности

Tue, 02 Dec 2025 00:00:00 +0000

Почему вайб-кодинг не работает

С появлением AI-агентов разработка программного обеспечения изменилась кардинально. Я, как и многие разработчики, начал активно использовать Claude, Cursor и другие инструменты для автоматизации написания кода. Результаты поначалу впечатляли: за один вечер, занимаясь системным анализом, проектированием архитектуры и промпт-инжинирингом, я мог сгенерировать до 100 000 строк кода.

Процесс был увлекательным. Не нужно было вручную писать реализацию - достаточно было описать требования, обсудить с AI архитектурное видение, уточнить детали, и код появлялся сам. Я мог работать по вечерам над своими pet-проектами, общаясь с искусственным интеллектом как с коллегой. Это был настоящий вайб-кодинг - приятный, творческий процесс, не отягощённый рутиной.

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

Симптомы деградации кодовой базы

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


// в основной функции
data := processData(input)
result := transform(data, input) // внутри вызывает processData и combine

// func transform(data, input) {
// tmp := processData(input)
// ...
// result := combine(tmp, input)
// ...
// return reuslt
// }
//
// func combine(data, input) {
// result := processData(input) // та же функция, те же аргументы!
// ...
// return result
// }

Функция processData вызывалась трижды с одинаковыми аргументами, но это дублирование было скрыто внутри transform и combine. AI не отследил, что результат можно переиспользовать, и генерировал похожий код в разных функциях. Но это была лишь верхушка айсберга.

Копаясь глубже, я находил:

Функции с 15-20 параметрами, половина из которых передавалась просто насквозь
Циклические зависимости между пакетами, скрытые через интерфейсы
Дублирование бизнес-логики в трёх разных местах с небольшими вариациями
God объекты, которые знали обо всей системе
Слои абстракций, которые ничего не абстрагировали, а только усложняли код

Код становился неподдерживаемым. Через две недели проект превращался в то, что сложно назвать иначе как клоака. Добавление новой функциональности требовало всё больше времени. AI предлагал решения, которые работали, но ещё сильнее запутывали архитектуру. Каждое изменение тянуло за собой цепочку других изменений в неожиданных местах.

Я устал создавать проекты, которые живут две недели, а потом становятся legacy. Это были мои собственные pet-проекты, которые я делал для души. Я даже не говорю о production-системах - там такое вообще недопустимо. Хотелось заниматься разработкой и развитием продукта, а не археологическими раскопками в собственном коде.

Остановиться и разобраться

Я принял решение: нужно прекратить генерировать новые проекты, обречённые стать неподдерживаемыми, и разобраться в проблеме системно. Переключил фокус с кодогенерации на исследовательскую работу.

Главный вопрос исследования: как разрабатывать проекты с помощью AI-агентов так, чтобы они оставались развиваемыми и поддерживаемыми?

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

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

Я начинаю цикл статей про исследование контроля архитектуры, рассматривая её как графовую структуру данных. В этой первой статье я покажу, как автоматически строить два вида архитектурных графов: структурный (статический) и поведенческий (динамический). Все примеры основаны на реальном проекте archlint - инструменте для автоматического построения и валидации архитектурных графов, который я разработываю в процессе исследования.

В следующих статьях цикла рассмотрю валидацию архитектурных правил и метрики качества кода на основе теории графов.

Структурная архитектура: статический граф системы

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

Зачем нужна формальная модель структуры

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

С AI-агентами ситуация другая. Агент работает в ограниченном контексте, не имеет глобального видения системы, не помнит архитектурные решения, принятые неделю назад. Каждый раз, генерируя код, он видит лишь фрагмент системы в окне контекста.

Результат предсказуем: архитектура деградирует. Появляются циклические зависимости, дублирование кода, нарушается слоистая структура. Неформальные соглашения не работают - их некому соблюдать.

Формальное решение: сделать архитектуру явной, автоматически проверяемой. Нужна математическая модель, которая точно описывает структуру системы и позволяет автоматически валидировать её корректность.

Граф - формальная модель

Структурную архитектуру можно представить через математическую абстракцию - ориентированный граф G = (V, E), где:

V (vertices) - множество узлов, представляющих компоненты системы
E (edges) - множество рёбер, представляющих связи между компонентами

Каждый узел v ∈ V имеет:

id - уникальный идентификатор (например, полное имя пакета или функции)
type - тип компонента (package, struct, function, method, interface)
properties - дополнительные свойства (имя файла, строка кода, видимость)

Каждое ребро e ∈ E имеет:

from - узел-источник
to - узел-приёмник
type - семантика связи (contains, calls, uses, imports, embeds)

Эта простая модель оказывается достаточно мощной для описания реальных систем. Граф позволяет:

Визуализировать архитектуру на разных уровнях абстракции
Валидировать архитектурные правила (например, “слой UI не должен зависеть от слоя DB”)
Вычислять метрики (связность, цикломатическая сложность, глубина зависимостей)
Отслеживать изменения во времени

Реальный пример: архитектура archlint

Рассмотрим структурную архитектуру проекта - archlint. Это инструмент для построения и анализа архитектурных графов, написанный на Go. Давайте посмотрим, как его структура выглядит в виде графа.

Пакетный уровень:

1
2
3
4
5
6
7
8


cmd/archlint - главный бинарник для сбора архитектуры
cmd/tracelint - линтер для проверки покрытия трейсингом
internal/analyzer - анализ исходного кода Go через AST
internal/model - модель графа архитектуры
internal/cli - реализация CLI команд
internal/linter - валидация корректности трейсинга
pkg/tracer - библиотека для трейсинга выполнения
tests/testdata/sample - тестовые примеры с инструментацией

Типы данных:

Типы данных организованы по доменам:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


// Модель графа
internal/model.Graph - представление архитектурного графа
internal/model.Node - узел графа (компонент системы)
internal/model.Edge - ребро графа (связь между компонентами)

// Анализатор исходного кода
internal/analyzer.GoAnalyzer - главный анализатор Go кода
internal/analyzer.PackageInfo - информация о пакете
internal/analyzer.TypeInfo - информация о типе (struct/interface)
internal/analyzer.FunctionInfo - информация о функции
internal/analyzer.MethodInfo - информация о методе
internal/analyzer.FieldInfo - информация о поле структуры
internal/analyzer.CallInfo - информация о вызове функции

// Трейсинг выполнения
pkg/tracer.Trace - трассировка выполнения теста
pkg/tracer.Call - отдельный вызов функции в trace
pkg/tracer.Context - контекст выполнения (набор вызовов)
pkg/tracer.SequenceDiagram - sequence диаграмма из trace
pkg/tracer.SequenceCall - вызов в sequence диаграмме
pkg/tracer.UMLConfig - конфигурация для генерации UML

Функции:

Функциональность распределена по пакетам согласно принципу единственной ответственности. Например, в internal/cli:

1
2
3
4
5


internal/cli.Execute - главная точка входа CLI
internal/cli.saveGraph - сохранение графа в файл
internal/cli.saveContexts - сохранение контекстов в файл
internal/cli.printContextsInfo - вывод информации о контекстах
internal/cli.runTrace - выполнение trace команды

Связи между компонентами:

Граф связей показывает зависимости между пакетами и типами данных:

Эта диаграмма показывает верхнеуровневую архитектуру. Видно, что:

Два бинарника (cmd/archlint и cmd/tracelint) используют разные подсистемы
Анализатор не зависит от CLI, его можно использовать независимо
Модель графа (internal/model) - центральная структура данных
Tracer - это публичная библиотека (pkg/tracer), которую могут использовать другие проекты

Автоматическое построение графа из исходного кода

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

Построение структурного графа происходит в четыре этапа:

Этап 1: Анализ исходного кода

Используя стандартный пакет go/ast, проходим по всем файлам проекта и строим абстрактное синтаксическое дерево (AST). AST даёт полную информацию о структуре кода: пакеты, импорты, типы, функции, методы, вызовы.

1

$ archlint collect . -o architecture.yaml

Команда рекурсивно анализирует все .go файлы в текущей директории и её поддиректориях.

Результат анализа:

1
2
3
4
5
6
7
8
9


Анализ кода: . (язык: go)
Найдено компонентов: 134
 - package: 8 # пакеты верхнего уровня
 - struct: 18 # структуры данных
 - type: 1 # type aliases
 - function: 55 # обычные функции
 - method: 28 # методы структур
 - external: 24 # внешние зависимости
Найдено связей: 189

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

Этап 2: Формирование узлов графа

Каждый найденный компонент становится узлом графа. Узлы имеют иерархическую структуру идентификаторов:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


components:
 - id: internal/analyzer
 title: analyzer
 entity: package

 - id: internal/analyzer.GoAnalyzer
 title: GoAnalyzer
 entity: struct

 - id: internal/analyzer.GoAnalyzer.Analyze
 title: Analyze
 entity: method

Идентификатор следует соглашениям Go: package.Type.Method. Это позволяет однозначно идентифицировать любой компонент системы.

Этап 3: Формирование рёбер графа

Создаём рёбра, выражающие семантику связей между компонентами:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


links:
 # Пакет содержит тип
 - from: internal/analyzer
 to: internal/analyzer.GoAnalyzer
 type: contains

 # Тип содержит метод
 - from: internal/analyzer.GoAnalyzer
 to: internal/analyzer.GoAnalyzer.Analyze
 type: contains

 # Функция вызывает другую функцию
 - from: internal/cli.Execute
 to: internal/analyzer.NewGoAnalyzer
 type: calls

 # Пакет импортирует другой пакет
 - from: cmd/archlint
 to: internal/cli
 type: imports

Разные типы рёбер позволяют различать семантику связей:

contains - отношение владения (пакет содержит тип, тип содержит метод)
calls - вызов функции или метода
uses - использование типа (например, в сигнатуре функции или поле структуры)
imports - импорт пакета
embeds - встраивание типа (embedding в Go)

Этап 4: Сохранение в формате YAML

На выходе получаем полный граф системы в формате YAML. Этот файл можно:

Визуализировать: Генерировать диаграммы с помощью PlantUML, Graphviz, или веб-интерфейсов вроде DocHub.

Валидировать: Проверять архитектурные правила. Например:

“Пакет internal/model не должен зависеть ни от чего, кроме стандартной библиотеки”
“Циклические зависимости между пакетами запрещены”
“Максимальная глубина вложенности вызовов - 5 уровней”

Анализировать: Вычислять метрики:

Связность графа (сколько компонентов связаны)
Цикломатическая сложность
Глубина дерева зависимостей
Coupling и cohesion метрики

Отслеживать изменения: Сравнивать версии графа, видеть эволюцию архитектуры во времени.

Структурный граф archlint - это полное, формальное описание статической структуры системы, которое автоматически обновляется и может быть проверено при каждом коммите.

Поведенческая архитектура: динамический граф выполнения

Структурная архитектура показывает, что система может делать - все потенциальные пути выполнения. Но она не отвечает на вопрос: что система реально делает? Какие компоненты используются в конкретных сценариях? Как данные проходят через систему?

Для ответа на эти вопросы нужна поведенческая архитектура - динамическая картина выполнения системы.

Зачем нужна поведенческая архитектура

Представьте большую систему со структурным графом из тысяч компонентов. Вы добавляете новую фичу. Какие компоненты реально используются? Какие пути выполнения проходит запрос?

Без поведенческой архитектуры вы можете только догадываться, читая код. С ней - вы видите точную последовательность вызовов, построенную из реального выполнения.

Поведенческая архитектура критически важна для:

Понимания сложных сценариев - видеть последовательность действий
Оптимизации производительности - находить узкие места в реальных путях выполнения
Выявления мёртвого кода - функции, которые не вызываются ни в одном сценарии
Документирования - автоматические sequence диаграммы вместо ручного рисования
Контроля покрытия - какие бизнес-сценарии покрыты acceptance тестами

Как acceptance тесты формируют поведенческую архитектуру

Ключевая идея: поведенческая архитектура не придумывается абстрактно - она извлекается из реального исполняемого кода. Источник - acceptance тесты.

Принцип “одна задача - один acceptance test”:

При правильной декомпозиции работы каждая задача имеет acceptance test, который проверяет корректность реализации. Acceptance test описывает конкретный сценарий использования системы - он задаёт контекст выполнения.

Например:

Задача “Калькулятор с памятью” -> acceptance test TestCalculateWithMemory
Задача “Экспорт отчёта в PDF” -> acceptance test TestExportReportToPDF
Задача “OAuth авторизация” -> acceptance test TestOAuthLogin

Каждый такой тест задаёт отдельный контекст - изолированный сценарий использования системы.

Процесс построения поведенческого графа:

flowchart LR feature[Фича:
Calculate with Memory] test[Acceptance Test:
TestCalculateWithMemory] trace[Trace File:
test_calculate.json] seq[Sequence Diagram:
PlantUML] behgraph[Behavioral Graph:
Numbered Edges] context[Context:
CalculateWithMemory] feature --> test test --> trace trace --> seq trace --> behgraph seq --> context behgraph --> context style feature fill:#e1f5ff style test fill:#fff4e1 style trace fill:#f0f0f0 style context fill:#d4edda

Фича - бизнес-требование или задача
Acceptance test - код, проверяющий фичу
Trace - полная последовательность вызовов при выполнении теста
Sequence diagram - визуализация последовательности взаимодействий
Behavioral graph - граф с пронумерованными рёбрами
Context - формализованный контекст выполнения фичи

Реальный пример: контекст “Calculate With Trace”

Рассмотрим реальный acceptance тест из проекта archlint.example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


func TestCalculateWithTrace(t *testing.T) {
 // Создаём директорию для трейсов
 traceDir := "traces"
 os.MkdirAll(traceDir, 0755)

 // Запускаем трассировку
 trace := tracer.StartTrace("TestCalculateWithTrace")
 defer func() {
 trace = tracer.StopTrace()
 if trace != nil {
 trace.Save(filepath.Join(traceDir, "test_calculate.json"))
 }
 }()

 // Выполняем сценарий acceptance теста
 calc := NewCalculator() // создаём калькулятор
 result := calc.Calculate(5, 3) // вычисляем (5 + 3) * 2 = 16

 // Проверяем acceptance критерий
 if result != 16 {
 t.Errorf("Expected 16, got %d", result)
 }
}

Тест выглядит как обычный Go test, но с добавлением трейсинга. tracer.StartTrace и tracer.StopTrace оборачивают выполнение сценария.

Инструментарий кода:

Все функции системы содержат точки трейсинга:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


func NewCalculator() *Calculator {
 tracer.Enter("sample.NewCalculator")
 defer tracer.ExitSuccess("sample.NewCalculator")
 return &Calculator{memory: 0}
}

func (c *Calculator) Calculate(a, b int) int {
 tracer.Enter("sample.Calculator.Calculate")
 defer tracer.ExitSuccess("sample.Calculator.Calculate")

 sum := Add(a, b) // trace зафиксирует вызов
 product := Multiply(sum, 2) // trace зафиксирует вызов
 c.AddToMemory(product) // trace зафиксирует вызов
 return c.GetMemory() // trace зафиксирует вызов
}

func Add(a, b int) int {
 tracer.Enter("sample.Add")
 defer tracer.ExitSuccess("sample.Add")
 return a + b
}

func Multiply(a, b int) int {
 tracer.Enter("sample.Multiply")
 defer tracer.ExitSuccess("sample.Multiply")
 return a * b
}

Трейсинг минимальный: tracer.Enter в начале функции, tracer.ExitSuccess в конце (через defer). Это не влияет на логику, только фиксирует факт вызова.

Результат трассировки:

После выполнения теста получаем JSON файл с полной последовательностью всех вызовов:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44


{
 "test_name": "TestCalculateWithTrace",
 "start_time": "2025-12-07T21:33:05.550942+03:00",
 "end_time": "2025-12-07T21:33:05.550946+03:00",
 "calls": [
 {
 "event": "enter",
 "function": "sample.NewCalculator",
 "timestamp": "2025-12-07T21:33:05.550942+03:00",
 "depth": 0
 },
 {
 "event": "exit_success",
 "function": "sample.NewCalculator",
 "timestamp": "2025-12-07T21:33:05.550942+03:00",
 "depth": 0
 },
 {
 "event": "enter",
 "function": "sample.Calculator.Calculate",
 "timestamp": "2025-12-07T21:33:05.550942+03:00",
 "depth": 0
 },
 {
 "event": "enter",
 "function": "sample.Add",
 "timestamp": "2025-12-07T21:33:05.550943+03:00",
 "depth": 1
 },
 {
 "event": "exit_success",
 "function": "sample.Add",
 "timestamp": "2025-12-07T21:33:05.550943+03:00",
 "depth": 1
 },
 {
 "event": "enter",
 "function": "sample.Multiply",
 "timestamp": "2025-12-07T21:33:05.550943+03:00",
 "depth": 1
 },
 ...
 ]
}

Каждое событие содержит:

event - тип события (enter/exit_success/exit_error)
function - полное имя функции
timestamp - точное время вызова
depth - уровень вложенности (0 = top-level, 1 = первый вызов, и т.д.)

Поле depth позволяет восстановить иерархию вызовов: какая функция из какой была вызвана.

Автоматическая генерация контекста:

Из trace файла автоматически генерируется контекст:

1

$ archlint trace ./traces -o contexts.yaml

Результат - формальное описание контекста в YAML:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


contexts:
 tests.testcalculatewithtrace:
 title: Calculate With Trace
 location: Tests/Calculate With Trace
 presentation: plantuml
 components:
 - sample.new_calculator
 - sample.calculator.calculate
 - sample.add
 - sample.multiply
 - sample.calculator.add_to_memory
 - sample.calculator.get_memory
 uml:
 file: output/traces/test_calculate.puml

Контекст включает:

title - человекочитаемое название
location - место в иерархии контекстов
components - список всех компонентов, участвующих в сценарии
uml.file - путь к автоматически сгенерированной PlantUML диаграмме

Визуализации: sequence диаграмма и граф

Из одного trace можно получить два разных представления: sequence диаграмму и поведенческий граф.

Sequence диаграмма показывает последовательность взаимодействий между компонентами во времени:

sequenceDiagram participant Test participant Calculator participant Add participant Multiply participant Memory Test->>Calculator: Calculate(5, 3) Calculator->>Add: Add(5, 3) Add-->>Calculator: 8 Calculator->>Multiply: Multiply(8, 2) Multiply-->>Calculator: 16 Calculator->>Memory: AddToMemory(16) Calculator->>Memory: GetMemory() Memory-->>Calculator: 16 Calculator-->>Test: 16

Sequence диаграмма удобна для понимания последовательности действий: кто кого вызывает, в каком порядке, какие данные передаются. Это классическое UML представление, знакомое всем разработчикам.

Поведенческий граф представляет те же данные в виде графа с пронумерованными рёбрами:

graph TD test[TestCalculateWithTrace] newCalc[NewCalculator] calc[Calculator.Calculate] add[Add] mult[Multiply] addMem[AddToMemory] getMem[GetMemory] test -->|1| newCalc test -->|2| calc calc -->|3| add calc -->|4| mult calc -->|5| addMem calc -->|6| getMem style test fill:#e1f5ff style calc fill:#fff4e1 style add fill:#f0f0f0 style mult fill:#f0f0f0

Граф компактнее sequence диаграммы и лучше подходит для анализа. Номера на рёбрах показывают порядок вызовов.

Ключевые особенности поведенческого графа:

Рёбра пронумерованы - сохраняется порядок выполнения
Мультиграф - между двумя узлами может быть несколько рёбер (если функция вызывалась несколько раз)
Контекстно-зависимый - показывает конкретный сценарий, не все возможные пути
Подграф структурного графа - каждый узел поведенческого графа существует в структурном графе

Метрики покрытия поведенческой архитектуры

Acceptance тесты напрямую определяют полноту поведенческой архитектуры. Каждый acceptance test создаёт один контекст. Совокупность всех контекстов - это полная поведенческая архитектура системы.

Ключевые метрики:

Покрытие компонентов:

1

coverage = (вызванные компоненты) / (всего компонентов) * 100%

Например, если в структурном графе N компонентов, а в acceptance тестах вызвано M компонентов, то покрытие = M/N * 100%.

Количество контекстов:

Чем больше acceptance тестов, тем больше контекстов, тем полнее покрытие различных сценариев использования.

Покрытие критических путей:

Не все компоненты одинаково важны. Можно пометить критические бизнес-сценарии и отслеживать их покрытие отдельно.

Обнаружение мёртвого кода:

Если компонент присутствует в структурном графе, но не встречается ни в одном контексте - это кандидат на удаление. Либо код мёртвый, либо не хватает acceptance тестов.

В реальном проекте нужно стремиться к 80%+ покрытию критических путей acceptance тестами.

Заключение: два взгляда на архитектуру

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

Структурный граф показывает, как организован код: какие компоненты существуют и как они могут взаимодействовать. Это статическая картина потенциальных связей. Построение автоматизировано через анализ AST исходного кода.

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

Ключевое отличие: структурный граф содержит ВСЕ возможные связи, поведенческий - только те, что реально используются в бизнес-сценариях.

Что дальше

Сами по себе графы - это только фундамент. Интересное начинается, когда мы используем их для контроля качества архитектуры.

В следующих статьях цикла я покажу:

Валидация архитектурных правил - как проверять ограничения на графе: запрет циклических зависимостей, контроль слоистой архитектуры, ограничения на глубину вызовов
Метрики теории графов - как измерять качество архитектуры через связность, центральность, модульность и другие метрики
Контроль AI-генерируемого кода - как использовать графы и метрики для предотвращения архитектурной деградации при разработке с AI-агентами

Инструменты

Все инструменты для построения архитектурных графов доступны в открытом репозитории: github.com/mshogin/archlint

Инструмент работает с Go-проектами, но подход универсален и применим к любому языку программирования.

Проект включает:

Анализатор Go кода для построения структурных графов
Библиотеку трейсинга для построения поведенческих графов
Генераторы визуализаций (PlantUML, Mermaid)
Примеры интеграции в CI/CD

Это результат исследовательской работы по вопросу “как разрабатывать с AI-агентами, сохраняя поддерживаемость”. Надеюсь, эти инструменты помогут и вам не превращать pet-проекты в “клоаку”, а создавать развиваемые системы.

Работа с хаосом в архитектуре

Mon, 28 Apr 2025 00:00:00 +0000

Когда работаешь с реальными системами, быстро понимаешь: большую часть времени ты не начинаешь с чистого листа.

Ты начинаешь с истории, компромиссов, наполовину реализованных идей и меняющихся приоритетов.

Поначалу это кажется беспорядком. Но со временем понимаешь кое-что важное: ясность не дается - она создается.

Чему научила меня работа с хаотичными архитектурами

Слушать, прежде чем судить. Каждое решение было принято в определенном контексте. Понять этот контекст важнее, чем спешить с выводами.

Искать паттерны, не навязывая их. Паттерны есть почти везде, но нужно дать им проявиться, а не форсировать их появление.

Строить небольшие опорные точки в нестабильной среде. Когда вокруг много неопределенности, важны маленькие устойчивые шаги.

И главное - оставаться терпеливым к сложности. Сложность - это не враг. Это реальность, с которой нужно научиться работать.

Каждая беспорядочная система хранит историю

И архитектура в лучшем своем проявлении - это понимание этой истории и помощь в написании следующей главы чуть лучше.

Если вы тоже работаете посреди хаоса: вы не делаете что-то не так. Скорее всего, вы находитесь именно там, где начинается настоящая архитектура.