Posts on Mikhail Shogin

AI Agent Linter Ecosystem: Quality, Cost and Safety Control

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

The Problem

AI agents write code fast, but speed comes at a cost. Literally - tokens cost money. And figuratively - code quality degrades without oversight.

I hit three problems at once:

Architecture degrades - agents write working code that violates layer boundaries, creates circular dependencies and god classes
Costs grow - complex prompts go to Opus at $15/1M tokens when Haiku at $0.80 would suffice
Content isn’t filtered - production prompts contain things that shouldn’t be there

Each problem has its own tool. But when the tools work together, they amplify each other.

The Pipeline

Every request passes through a chain of linters, each responsible for its domain:

seclint - checks content safety (6+/12+/16+/18+ ratings)
promptlint - scores complexity, picks the model
Agent - executes the task on the selected model
archlint - validates the result for architecture violations
costlint - records cost, tracks cache hit rate

If archlint rejects the result, the task escalates to a more powerful model. costlint records the escalation cost.

The Tools

archlint - Architecture Linter

Scans Go projects for structural violations.

1

archlint scan --format json ./project/

What it finds:

Layer violations (handler calls repository directly)
God classes (>20 methods or >15 dependencies)
Circular dependencies
Interface Segregation violations (interfaces >5 methods)

Metrics: fan-out, coupling (Ca/Ce), component and link counts.

GitHub: mshogin/archlint

promptlint - Complexity-Based Router

Scores prompt complexity and picks the model. No LLM, pure metrics, <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

Signals: length, sentence count, domain keywords, action type (fix/create/refactor), code presence.

Integrates with ccproxy for real Claude Code request routing through a proxy.

GitHub: mikeshogin/promptlint

costlint - Token Cost Analysis

Tracks spending, analyzes caching, runs A/B tests between models.

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 metrics: hit rate, block reuse, content entropy, Jaccard similarity. A/B testing: 30/30/40 traffic split, per-group cost and quality metrics.

GitHub: mikeshogin/costlint

seclint / promptsec - Content Filter

Age ratings for prompts: 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"]}

Considers educational context - explaining SQL injection for a security course gets 16+ instead of 18+.

GitHub: mikeshogin/seclint / mikeshogin/promptsec

Shared Principles

All tools follow the same rules:

Go - single stack, single build
No LLM - pure metrics, regex, keyword matching. <10ms per request
CLI + HTTP - each tool works as a command and as a server
JSONL telemetry - unified log format for analysis
Pipeline-friendly - exit codes, stdout, pipes

Numbers

On test workload (342 requests over a week):

Metric	Before	After
Token spending	$19.54	$8.20
Architecture violations	63	12
Requests to expensive model	100% opus	14% opus
Routing latency	-	<10ms

58% cost savings without quality loss - simple tasks go to Haiku, architecture tasks stay on Opus.

Orchestration

The tools work autonomously, but deliver maximum impact together. For orchestration we use myhome - daemon-based AI agent management with workflow stages and scheduled tasks.

The stack:

myhome launches agents
promptlint picks the model (pre-route hook)
archlint validates output (quality gate stage)
costlint tracks cost (telemetry consumer)
seclint filters incoming prompts (pre-filter)

Get Started

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


# Install all tools
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

# Start routing
promptlint serve 8090 &
seclint serve 8091 &

# Check architecture
archlint scan --format json ./my-project/

# View costs
costlint report --source ~/.promptlint/telemetry.jsonl

Three blockers that prevent technical leaders from growing

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

AI is changing IT faster than we can adapt. Roles are transforming. Skills that paid well yesterday are losing value today.

To maintain your standard of living, you need to grow. But growth doesn’t stall because of technology. Not because of your stack. Not because of certifications.

It stalls because of how you think.

Strong professionals get stuck. Not because they lack knowledge. But because there are internal blockers that are hard to see on your own.

I’ve been working with system architecture for over fifteen years. And in recent years I’ve noticed: the most serious bugs aren’t in code. They’re in the heads of people who write that code and manage those who write it.

Here are three patterns I see most often. In others. And in myself.

Blocker 1: Territory defense

Every leader has a zone of responsibility. And any entry into it feels like an attack. It’s instinct - like a predator patrolling its boundaries.

What it looks like

Imagine this. You’re an architect. A system analyst on your team starts making architectural decisions independently. Doing a decent job, but without checking with you. You see the result - the decisions work, but you feel an irritation inside that’s hard to explain rationally.

In a meeting, you start pushing back. Not because the decision was bad - but because it was made without you. Officially you’re talking about quality and process. In reality, you’re defending territory.

Another example. A team lead notices that a senior on the team is starting to take on architectural questions. Instead of giving space and helping them grow, the lead tightens control. More reviews. More approvals. More questions like “did you think about…”. Officially - concern for quality. In reality - fear of becoming unnecessary.

Why this is a blocker

The problem isn’t defense. Protecting boundaries is normal.

The problem is HOW you defend them. From confidence in your abilities - or from fear that something will be taken away? The first is leadership. The second is aggression that people feel. And they leave.

If we draw an analogy with systems: it’s like a microservice that instead of providing an API for interaction, closes all ports and returns 403 to every request. Technically it works. But the system around it degrades.

The skill

Distinguish real threats from phantom ones. One question to yourself: “am I protecting quality right now - or protecting my ego?”

Blocker 2: Craving recognition

This is really about feedback.

What it looks like

You did excellent work. Designed a system that handles the load. Ran a review process that raised code quality across the team. Solved a problem that nobody could crack for six months.

And silence. Nobody came over and said “great work.” Your manager is quiet. The team took the result for granted.

In that silence, your brain starts filling in the gaps: “I must be doing a bad job.” Or worse: “they don’t value what I do.”

A familiar story: an architect built an API review process for system analysts. Specification quality went up. Integration-phase bugs went down. But the manager never once said “good work.” At some point the architect started wondering - was it even worth spending time on this.

Another example. A senior developer spent a month refactoring a critical module. Code got cleaner, tests more reliable, deploy time cut in half. At the retro, nobody even mentioned it. The senior started losing motivation - not because the work was meaningless, but because nobody noticed.

Why this is a blocker

In adult life, nobody will come and say “well done.” Parents did that. At work - silence. And in that silence, your brain starts making things up.

Looking at it as a system: you have no observability for your own value. No metrics, no dashboard, no alerts. You’re working blind and relying on a single indicator - external praise. And that indicator is unreliable. It depends on your manager’s mood, on company culture, on a thousand factors you don’t control.

The skill

Either learn to ask for feedback - that’s not weakness, it’s maturity. Or build an internal foundation that doesn’t depend on other people’s words.

Practically: keep your own achievement log. Once a week, write down what you did and what effect it had. In six months you’ll have an objective picture - regardless of whether your manager noticed.

Blocker 3: The experience trap

Deep experience creates an illusion: “I know more, therefore I’m owed something.”

What it looks like

A meeting. You’re the most experienced person in the room. A junior proposes a solution. You see problems in it. And instead of asking a question - “what happens at 10x load?” - you say: “no, that’s not how it’s done, I’ve been doing this for ten years and I know.”

Technically you’re right. The solution might not handle the load. But you killed two things: the junior’s initiative and the team’s ability to learn to think independently.

Another example. An experienced team lead joins a new team. They have three successful projects behind them using a specific stack. The team uses a different approach. Instead of understanding why that approach was chosen, the lead starts pushing their own. Not because it’s better - but because it’s familiar. And because accepting someone else’s approach means accepting that your experience isn’t universal.

I catch myself doing this. Sometimes I push with experience instead of listening. And every time I catch myself, I ask: am I teaching right now - or proving?

Why this is a blocker

The world is transforming. Old patterns are breaking down. In the age of AI, yesterday’s expert is learning from scratch today. Experience is valuable, but it’s not currency to exchange for submission.

As a system analogy: it’s a legacy service with hardcoded configuration. It used to work perfectly. But the world around it changed, and it still expects requests in the old format. And instead of adapting its API, it demands that everything else adapts to it.

The skill

Treat colleagues as equals. Regardless of the experience gap. This doesn’t mean ignoring your experience - it means sharing it through questions, not through pressure.

Three blockers. Three skills. None about technology

Territory defense, craving recognition, the experience trap. These patterns can’t be solved by reading books or taking courses. They’re embedded in your thinking architecture so deeply that they’re hard to see on your own.

Like in any project: to see architectural problems, you need an outside perspective. The one inside the system sees individual symptoms. The one outside sees the pattern.

Leadership starts not with the architecture of systems, but with the architecture of thinking. And if you feel stuck - maybe it’s not that you don’t know enough. Maybe it’s time to look at your thinking as a system and run an honest audit on it.

Фаулер про 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: Controlling AI Code Generation

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

Observations

4000 lines in a single MR. Three hours reviewing, 12 comments, fixes - another 800 lines. On the fourth attempt I closed the tab and realized: the problem isn’t the code, it’s that nobody knew what exactly needed to be written.

If you work with large codebases, this situation is familiar. Large MRs are a symptom. When it’s unclear what exactly needs to be done, developers write more code than necessary. They add things just in case. Cover scenarios nobody asked for. The MR grows not because the task is big, but because the boundaries are fuzzy.

Another cause is the illusion that it’s easier to do everything in one task than to decompose. It seems like splitting creates extra work. In practice, a monolithic 4000-line MR can’t be properly reviewed, and bugs slip through to production.

I use AI daily. Claude Code is my main tool - it can be configured to use different models: Anthropic, DeepSeek, GPT family, local ones via Ollama. At some point I noticed a pattern: the more precisely I formulate the task, the better the result. Prompts became increasingly structured - simple instructions, then templates, then something resembling technical specifications.

Where’s the problem? At first I thought I was too lazy to give AI detailed instructions. Then I decided the AI Agent wasn’t gathering enough context - needed RAG or something similar. Eventually I realized the problem is in both places: creating full instructions feels like overkill, and how to help the agent gather the right context - unclear.

But the main thing - there’s nothing to verify. No artifact you can point to and say: this is what was specified, this is what was built.

Hypothesis

The idea isn’t new - the industry has been talking about spec-first approach for a while. I wanted to try it for a long time and finally decided to test it.

If requirements are formalized as a specification before coding begins, then:

AI Agent will generate more predictable code
Results can be validated against the specification
Architecture will remain controllable

When AI Agent generates hundreds of lines of code per minute, the only way to control the result is to have a formal description of what should be produced, and a tool that verifies the implementation matches the specification. More on the latter in a separate article.

Method

I decided to test the hypothesis on a real project - a tool for building architectural graphs from Go code. The rule was simple: not a single line of code without a specification.

First specification - create an empty project with standard Go layout. Second - graph model. Third - Go code analyzer. Over several days, 10 completed specifications accumulated.

Storage Structure

Kanban-like organization via file system:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


specs/
├── todo/ # task queue
│ ├── 0010-feature-x.md
│ └── 0020-feature-y.md
├── inprogress/ # in progress (maximum one - WIP limit)
│ └── 0005-current.md
└── done/ # completed
 ├── 0001-init-project.md
 ├── 0003-data-model.md
 └── 0004-go-analyzer.md

Prioritization via numeric prefix: lower number - higher priority. State transitions - moving files between directories.

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

Specification Sizes

Classification by time to write the specification (T-shirt sizing):

S (Small) - up to 10 minutes
M (Medium) - 10-20 minutes
L (Large) - more than 20 minutes

Size determines depth of elaboration. S-task: Problem Statement and 5 Acceptance Criteria. L-task: full UML/C4 diagrams, detailed Requirements, 15+ acceptance criteria. Correlation between specification size and result predictability is direct.

If you’re starting from scratch - try an S-specification first. Minimal investment for the experiment.

S-Specification Example: Project Initialization

 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


# Spec 0001: Initialize Standard Golang Project Layout

**Metadata:**
- Priority: 0001
- Status: Done
- Effort: S

## Overview
### Problem Statement
Need to create basic Go project structure for the archlint tool
according to standard development practices.

### Solution Summary
Initialize Go module and create minimal project structure.

## Requirements
### R1: Go Module Initialization
- Initialize Go module with name github.com/mshogin/archlint

### R2: Minimal Directory Structure
- Create cmd/archlint/ for entry point
- Create internal/ for private code
- Create pkg/ for public libraries

## Acceptance Criteria
- [x] AC1: go.mod created with module path github.com/mshogin/archlint
- [x] AC2: cmd/archlint/main.go exists and compiles
- [x] AC3: Directories internal/ and pkg/ exist

Minimum details, maximum specificity. AI gets clear task boundaries.

M-Specification Example: Collect Command

Medium tasks require diagrams. I experimented with Sequence diagrams - sending them to the agent along with requirements. Noticed that with them the AI Agent produces roughly what’s expected.

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


# Spec 0006: Implement Collect Command

**Metadata:**
- Priority: 0006
- Status: Done
- Effort: M

## Overview
### Problem Statement
Need to implement the collect command for gathering architecture
from source code and saving the graph to a YAML file.

### Solution Summary
Create a collect subcommand that uses GoAnalyzer to analyze code
and saves the result in YAML format.

## Architecture
### Sequence Flow (PlantUML)

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


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"

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


## Requirements
### R1: Command Definition
var collectCmd = &cobra.Command{
 Use: "collect [directory]",
 Short: "Collect architecture from source code",
 Args: cobra.ExactArgs(1),
 RunE: runCollect,
}

### R2: Flags
-o, --output: output YAML file (default: architecture.yaml)
-l, --language: programming language (default: go)

## Acceptance Criteria
- [x] AC1: Command accepts directory as argument
- [x] AC2: Flags -o and -l work
- [x] AC3: Result saved to YAML
- [x] AC4: Statistics printed for components

Sequence diagram defines call order. AI follows it literally.

L-Specification Example: Go Code Analyzer

Large tasks require multiple diagrams - Data Model and Sequence:

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


# Spec 0004: Implement Go Code Analyzer

**Metadata:**
- Priority: 0004
- Status: Done
- Effort: L

## Overview
### Problem Statement
Need to implement a Go code analyzer that parses source code
using AST and builds a dependency graph between components.

### Solution Summary
Create GoAnalyzer in internal/analyzer package that uses
go/ast and go/parser to analyze Go files and build the graph.

## Architecture
### Data Model

 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


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

1

### Sequence Diagram

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


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

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


## Requirements
### R1: AST Parsing
- Parse all .go files in directory
- Extract packages, types, functions, methods

### R2: Graph Building
- Create Node for each component
- Create Edge for each relationship (import, calls, uses)

### R3: External Dependencies
- Identify external dependencies
- Mark them as entity: external

## Acceptance Criteria
- [x] AC1: Analyzer correctly parses Go code
- [x] AC2: All component types extracted
- [x] AC3: All relationship types identified
- [x] AC4: External dependencies identified
- [x] AC5: Graph serializes to YAML

For L-tasks multiple diagrams are a necessity. Data Model, Sequence, Component - together they define application architecture and manage dependencies between components.

The Role of AI

AI accelerates the work, but I don’t delegate architecture: decisions are fixed in the specification, go through review, and are verified by validators. However, decisions rarely come from thin air: I bring initial options and constraints, the agent suggests alternatives and highlights blind spots. This affects my thinking, and I’m aware of it. The final yes/no and responsibility are mine.

The agent has two areas of responsibility.

Specification Editor I dictate a raw stream of thoughts by voice (I dictate faster than I type). The agent formats it according to my specification template: organizes into sections, clarifies the unsaid, formulates requirements and acceptance criteria so they can be verified. After that I review and fix the specification as the source contract.
Implementation Executor When the specification is agreed upon, I hand it to the agent for implementation. The agent writes code according to the specification, and I verify the result: review, validation, iterations until the architecture becomes clean and predictable.

graph LR A["Ideas/options (me)"] --> B["AI supplements and formalizes"] B --> C["Specification"] C --> D["Review and decisions (me)"] D --> E["Implementation (AI)"]

Results

Over several days - 10 completed specifications and a working project. Code matches the architecture from diagrams.

To test whether specifications are self-sufficient, I ran an experiment: gave Claude Code an empty directory and 10 specifications from archlint - no access to source code. The task: recreate the project from scratch.

Result in 20 minutes:

85.5% reproduction success rate
100% structural identity (directories, files, types)
23 mutations in implementation details

Project structure reproduced completely. All acceptance criteria from specifications met. Project compiles and passes tests.

Mutations occurred where specifications described what to do, but not how. Critical example: the sequence diagram building algorithm was implemented differently - functionally equivalent, but with different call stack traversal logic. Another category of mutations - stylistic: comment language, function order in files, variable naming.

Takeaway for improving specifications: critical algorithms need pseudocode or concrete input/output examples. A specification with what + how yields more precise reproduction than what alone.

Full report with mutation catalog: github.com/mshogin/archlint-reproduction

Specification Idempotency

For specifications to remain reproducible, all changes must go through them. No tweaks in copilot mode, no chats with “fix this thing”. Every change - update the specification, then implement.

This is the main challenge. You want to quickly fix a bug in dialogue rather than go back to the spec. But every such fix - loss of reproducibility.

The trade-off is obvious:

Need results here and now - copilot mode is faster
Need reproducibility - only through specifications

The choice depends on context. Prototype or experiment - copilot. Production code with a long lifecycle - specifications.

Limitations

The approach doesn’t solve problems automatically. It doesn’t replace domain understanding, doesn’t invent requirements, and doesn’t guarantee good design. It makes errors visible earlier and forces architecture to stay within bounds.

The cost: time for writing specifications, reviewing them, and iterations after validation. If you treat specs formally, everything slides back into chaos. Honestly ask yourself: are you willing to spend 10-30 minutes on a specification so the agent can implement it in 5-20 minutes?

Implementation details vary. The reproducibility experiment showed 23 mutations - algorithms are interpreted differently, code style differs. Critical sections need pseudocode, not just descriptions.

I think the approach works well where there’s an established, formed, and working process. Processes focused on discipline, clear areas of responsibility, review, definition of done. You can think of this process as a conveyor delivering software 24/7.

Conclusions

The hypothesis was confirmed:

AI generates more predictable code - yes, with diagrams present
Results can be validated - yes, 85.5% reproducibility
Architecture remains controllable - yes, 100% structural identity

The essence is simple: without specification there’s nothing to verify, with specification - there’s an artifact for validation. No need for perfect AI or perfect prompt.

The experiment continues.

Templates and examples: github.com/mshogin/archlint

If you’re trying the spec-driven approach or already using it - share in the comments what works and what doesn’t. I write about AI code generation and architecture practices on Telegram: @MikeShogin

Structural and Behavioral Architecture: Graph-Based Approach to Complexity Control

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

Why Vibe Coding Doesn’t Work

With the emergence of AI agents, software development has changed dramatically. Like many developers, I started actively using Claude, Cursor, and other tools to automate code writing. The results were initially impressive: in one evening, doing system analysis, architecture design, and prompt engineering, I could generate up to 100,000 lines of code.

The process was engaging. There was no need to manually write implementations - just describe requirements, discuss architectural vision with AI, clarify details, and code would appear. I could work on my pet projects in the evenings, talking with artificial intelligence like a colleague. This was true vibe coding - a pleasant, creative process unburdened by routine.

Problems didn’t start immediately. The first few days went smoothly: AI quickly generated code, tests passed, functionality worked. But then, after about a week or two of active development, I began noticing alarming symptoms.

Symptoms of Codebase Degradation

Agents started slowing down. What used to take minutes now required tens of minutes. AI began looping on simple tasks, generating excessive code, suggesting refactoring almost the entire project to fix a small bug. The context grew too large, and the agent got lost in its own code.

Architectural anti-patterns appeared. The last straw was when reviewing code I discovered this construction:

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


// in the main function
intermediate := transform(input) // inside calls processData(input)
final := combine(intermediate) // inside calls processData(input) again!

// func transform(input) {
// tmp := processData(input)
// result := combine(input)
// ...
// return reuslt * 2
// }
//
// func combine(intermediate) {
// result := processData(input) // same function, same arguments!
// return intermediate + result
// }

The processData function was called twice with identical arguments, but this duplication was hidden inside transform and combine. AI didn’t track that the result could be reused and generated similar code in different functions. But this was just the tip of the iceberg.

Digging deeper, I found:

Functions with 15-20 parameters, half of which were passed straight through
Circular dependencies between packages hidden through interfaces
Duplication of business logic in three different places with slight variations
God objects that knew about the entire system
Layers of abstractions that abstracted nothing but only complicated the code

Code became unmaintainable. After two weeks, the project turned into what’s hard to call anything other than a mess. Adding new functionality required more and more time. AI proposed solutions that worked but further tangled the architecture. Every change pulled a chain of other changes in unexpected places.

I got tired of creating projects that live two weeks and then become legacy. These were my own pet projects that I did for fun. I’m not even talking about production systems - that’s completely unacceptable there. I wanted to do development and product growth, not archaeological digs in my own code.

Stop and Understand

I made a decision: stop generating new projects doomed to become unmaintainable and systematically understand the problem. Shifted focus from code generation to research work.

The main research question: how to develop projects with AI agents so they remain evolvable and maintainable?

After analyzing the problem, I came to a key conclusion: vibe coding without formal architecture control is a dead end. AI agents excellently generate code that works here and now. But they don’t see the big picture of architecture, don’t track accumulation of technical debt, don’t notice emerging anti-patterns.

An engineering approach is needed: formal architecture description, automatic validation, quality metrics. Architecture must be explicit, verifiable, controlled. Only this way can codebase degradation be prevented.

I’m starting a series of articles on architecture control research, viewing it as a graph data structure. In this first article, I’ll show how to automatically build two types of architectural graphs: structural (static) and behavioral (dynamic). All examples are based on a real project archlint - a tool for automatic construction and validation of architectural graphs that I’m developing during the research.

In subsequent articles of the series, I’ll cover validation of architectural rules and code quality metrics based on graph theory.

Structural Architecture: Static System Graph

When we talk about software system architecture, we often mean its structure: what components the system consists of, how they’re organized, how they’re connected to each other. Structural architecture is a static picture capturing potential connections between code elements.

Why a Formal Structure Model is Needed

In traditional development, structural architecture exists as diagrams in documentation, team conventions, knowledge in experienced developers’ heads. This suffices when code is written by people who understand context and keep the big picture in mind.

With AI agents, the situation is different. An agent works in limited context, has no global system vision, doesn’t remember architectural decisions made a week ago. Each time generating code, it sees only a fragment of the system in the context window.

The result is predictable: architecture degrades. Circular dependencies appear, code duplication, layered structure breaks. Informal conventions don’t work - there’s no one to follow them.

Formal solution: make architecture explicit, automatically verifiable. A mathematical model is needed that accurately describes system structure and allows automatic validation of its correctness.

Graph as a Formal Model

Structural architecture can be represented through a mathematical abstraction - a directed graph G = (V, E), where:

V (vertices) - set of nodes representing system components
E (edges) - set of edges representing connections between components

Each node v ∈ V has:

id - unique identifier (e.g., full package or function name)
type - component type (package, struct, function, method, interface)
properties - additional properties (filename, code line, visibility)

Each edge e ∈ E has:

from - source node
to - target node
type - connection semantics (contains, calls, uses, imports, embeds)

This simple model turns out powerful enough to describe real systems. The graph allows:

Visualizing architecture at different abstraction levels
Validating architectural rules (e.g., “UI layer must not depend on DB layer”)
Computing metrics (connectivity, cyclomatic complexity, dependency depth)
Tracking changes over time

Real Example: archlint Architecture

Let’s examine the structural architecture of a real project - archlint. This is a tool for building and analyzing architectural graphs, written in Go. Let’s see how its structure looks as a graph.

Package Level (8 packages):

1
2
3
4
5
6
7
8


cmd/archlint - main binary for architecture collection
cmd/tracelint - linter for checking tracing coverage
internal/analyzer - Go source code analysis via AST
internal/model - architecture graph model
internal/cli - CLI commands implementation
internal/linter - tracing correctness validation
pkg/tracer - execution tracing library
tests/testdata/sample - test examples with instrumentation

Organization in internal/ vs pkg/ follows standard Go conventions: internal contains private packages used only inside the project, pkg - public libraries that other projects can use.

Data Types:

Data types are organized by domains:

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


// Graph model
internal/model.Graph - architectural graph representation
internal/model.Node - graph node (system component)
internal/model.Edge - graph edge (connection between components)

// Source code analyzer
internal/analyzer.GoAnalyzer - main Go code analyzer
internal/analyzer.PackageInfo - package information
internal/analyzer.TypeInfo - type information (struct/interface)
internal/analyzer.FunctionInfo - function information
internal/analyzer.MethodInfo - method information
internal/analyzer.FieldInfo - struct field information
internal/analyzer.CallInfo - function call information

// Execution tracing
pkg/tracer.Trace - test execution tracing
pkg/tracer.Call - individual function call in trace
pkg/tracer.Context - execution context (set of calls)
pkg/tracer.SequenceDiagram - sequence diagram from trace
pkg/tracer.SequenceCall - call in sequence diagram
pkg/tracer.UMLConfig - configuration for UML generation

Functions:

Functionality is distributed across packages according to single responsibility principle. For example, in internal/cli:

1
2
3
4
5


Internal/cli.Execute - main CLI entry point
internal/cli.saveGraph - save graph to file
internal/cli.saveContexts - save contexts to file
internal/cli.printContextsInfo - print contexts information
internal/cli.runTrace - execute trace command

Connections Between Components:

The connection graph shows dependencies between packages and data types:

This diagram shows high-level architecture. We can see that:

Two binaries (cmd/archlint and cmd/tracelint) use different subsystems
The analyzer doesn’t depend on CLI, can be used independently
The graph model (internal/model) is the central data structure
Tracer is a public library (pkg/tracer) that other projects can use

Automatic Graph Building from Source Code

Theoretical model is good, but automation is needed. Manually describing a graph of hundreds of components and connections is unrealistic. Moreover, the graph must automatically update with every code change.

Building the structural graph happens in four stages:

Stage 1: Source Code Analysis

Using the standard go/ast package, we go through all project files and build an abstract syntax tree (AST). AST gives complete information about code structure: packages, imports, types, functions, methods, calls.

1

$ archlint collect . -o architecture.yaml

The command recursively analyzes all .go files in the current directory and its subdirectories.

Analysis result:

1
2
3
4
5
6
7
8
9


Analyzing code: . (language: go)
Found components: 134
 - package: 8 # top-level packages
 - struct: 18 # data structures
 - type: 1 # type aliases
 - function: 55 # regular functions
 - method: 28 # struct methods
 - external: 24 # external dependencies
Found links: 189

Important point: external dependencies are also accounted for. These are packages from Go standard library and third-party modules used by the project. The complete dependency picture includes them.

Stage 2: Graph Node Formation

Each found component becomes a graph node. Nodes have a hierarchical identifier structure:

 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

The identifier follows Go conventions: package.Type.Method. This allows unambiguous identification of any system component.

Stage 3: Graph Edge Formation

We create edges expressing connection semantics between components:

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


links:
 # Package contains type
 - from: internal/analyzer
 to: internal/analyzer.GoAnalyzer
 type: contains

 # Type contains method
 - from: internal/analyzer.GoAnalyzer
 to: internal/analyzer.GoAnalyzer.Analyze
 type: contains

 # Function calls another function
 - from: internal/cli.Execute
 to: internal/analyzer.NewGoAnalyzer
 type: calls

 # Package imports another package
 - from: cmd/archlint
 to: internal/cli
 type: imports

Different edge types allow distinguishing connection semantics:

contains - ownership relationship (package contains type, type contains method)
calls - function or method call
uses - type usage (e.g., in function signature or struct field)
imports - package import
embeds - type embedding (embedding in Go)

Stage 4: Saving in YAML Format

The output is a complete system graph in YAML format. This file can be:

Visualized: Generate diagrams using PlantUML, Graphviz, or web interfaces like DocHub.

Validated: Check architectural rules. For example:

“Package internal/model must not depend on anything except standard library”
“Circular dependencies between packages are forbidden”
“Maximum call nesting depth is 5 levels”

Analyzed: Compute metrics:

Graph connectivity (how many components are connected)
Cyclomatic complexity
Dependency tree depth
Coupling and cohesion metrics

Track changes: Compare graph versions, see architecture evolution over time.

The structural graph of archlint is a complete, formal description of the system’s static structure that automatically updates and can be checked with every commit.

Behavioral Architecture: Dynamic Execution Graph

Structural architecture shows what the system can do - all potential execution paths. But it doesn’t answer the question: what does the system actually do? Which components are used in specific scenarios? How does data flow through the system?

To answer these questions, behavioral architecture is needed - a dynamic picture of system execution.

Why Behavioral Architecture is Needed

Imagine a large system with a structural graph of thousands of components. You’re adding a new feature. Which components are actually used? What execution paths does a request take?

Without behavioral architecture, you can only guess by reading code. With it - you see the exact sequence of calls built from actual execution.

Behavioral architecture is critically important for:

Understanding complex scenarios - seeing the sequence of actions
Performance optimization - finding bottlenecks in real execution paths
Identifying dead code - functions that aren’t called in any scenario
Documentation - automatic sequence diagrams instead of manual drawing
Coverage control - which business scenarios are covered by acceptance tests

How Acceptance Tests Form Behavioral Architecture

Key idea: behavioral architecture isn’t invented abstractly - it’s extracted from real executable code. The source is acceptance tests.

The “one task - one acceptance test” principle:

With proper work decomposition, each task has an acceptance test that verifies implementation correctness. An acceptance test describes a specific system usage scenario - it defines an execution context.

For example:

Task “Calculator with Memory” -> acceptance test TestCalculateWithMemory
Task “Export Report to PDF” -> acceptance test TestExportReportToPDF
Task “OAuth Authorization” -> acceptance test TestOAuthLogin

Each such test defines a separate context - an isolated system usage scenario.

Behavioral graph building process:

flowchart LR feature[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

Feature - business requirement or task
Acceptance test - code verifying the feature
Trace - complete call sequence during test execution
Sequence diagram - visualization of interaction sequence
Behavioral graph - graph with numbered edges
Context - formalized feature execution context

Real Example: “Calculate With Trace” Context

Let’s examine a real acceptance test from the archlint project:

 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) {
 // Create directory for traces
 traceDir := "traces"
 os.MkdirAll(traceDir, 0755)

 // Start tracing
 trace := tracer.StartTrace("TestCalculateWithTrace")
 defer func() {
 trace = tracer.StopTrace()
 if trace != nil {
 trace.Save(filepath.Join(traceDir, "test_calculate.json"))
 }
 }()

 // Execute acceptance test scenario
 calc := NewCalculator() // create calculator
 result := calc.Calculate(5, 3) // calculate (5 + 3) * 2 = 16

 // Check acceptance criterion
 if result != 16 {
 t.Errorf("Expected 16, got %d", result)
 }
}

The test looks like a regular Go test but with tracing added. tracer.StartTrace and tracer.StopTrace wrap scenario execution.

Code Instrumentation:

All system functions contain instrumentation points:

 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 will record the call
 product := Multiply(sum, 2) // trace will record the call
 c.AddToMemory(product) // trace will record the call
 return c.GetMemory() // trace will record the call
}

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
}

Instrumentation is minimal: tracer.Enter at function start, tracer.ExitSuccess at end (via defer). This doesn’t affect logic, only records the fact of the call.

Tracing Result:

After test execution, we get a JSON file with the complete sequence of all calls:

 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
 },
 ...
 ]
}

Each event contains:

event - event type (enter/exit_success/exit_error)
function - full function name
timestamp - exact call time
depth - nesting level (0 = top-level, 1 = first call, etc.)

The depth field allows reconstructing the call hierarchy: which function was called from which.

Automatic Context Generation:

A context is automatically generated from the trace file:

1

$ archlint trace ./traces -o contexts.yaml

Result - formal context description in 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

The context includes:

title - human-readable name
location - place in context hierarchy
components - list of all components participating in the scenario
uml.file - path to automatically generated PlantUML diagram

Visualizations: Sequence Diagram and Graph

From one trace, two different representations can be obtained: a sequence diagram and a behavioral graph.

Sequence diagram shows the sequence of interactions between components over time:

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

The sequence diagram is convenient for understanding the sequence of actions: who calls whom, in what order, what data is passed. This is a classic UML representation familiar to all developers.

Behavioral graph represents the same data as a graph with numbered edges:

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

The graph is more compact than the sequence diagram and better suited for analysis. Numbers on edges show call order.

Key features of the behavioral graph:

Edges are numbered - execution order is preserved
Multigraph - there can be multiple edges between two nodes (if the function was called multiple times)
Context-dependent - shows a specific scenario, not all possible paths
Subgraph of structural graph - each behavioral graph node exists in the structural graph

Behavioral Architecture Coverage Metrics

Acceptance tests directly determine the completeness of behavioral architecture. Each acceptance test creates one context. The totality of all contexts is the complete behavioral architecture of the system.

Key metrics:

Component coverage:

1

coverage = (called components) / (total components) * 100%

For example, if the structural graph has N components and M components are called in acceptance tests, then coverage = M/N * 100%.

Number of contexts:

The more acceptance tests, the more contexts, the more complete coverage of different usage scenarios.

Critical path coverage:

Not all components are equally important. Critical business scenarios can be marked and their coverage tracked separately.

Dead code detection:

If a component is present in the structural graph but doesn’t appear in any context - it’s a candidate for removal. Either the code is dead or acceptance tests are lacking.

In a real project, aim for 80%+ coverage of critical paths with acceptance tests.

Conclusion: Two Views of Architecture

In this article, I showed how to represent software system architecture through a graph data structure. Two types of graphs provide two different but complementary views of the system:

Structural graph shows how code is organized: what components exist and how they can interact. This is a static picture of potential connections. Construction is automated through AST analysis of source code.

Behavioral graph shows how the system actually works: which components are called in specific scenarios and in what sequence. This is a dynamic picture of actual execution paths. Construction is automated through acceptance test tracing.

Key difference: the structural graph contains ALL possible connections, behavioral - only those actually used in business scenarios.

What’s Next

Graphs themselves are just the foundation. The interesting part begins when we use them for architecture quality control.

In subsequent articles of the series, I’ll show:

Validation of architectural rules - how to check graph constraints: prohibition of circular dependencies, layered architecture control, call depth limits
Graph theory metrics - how to measure architecture quality through connectivity, centrality, modularity and other metrics
AI-generated code control - how to use graphs and metrics to prevent architectural degradation when developing with AI agents

Tools

All tools for building architectural graphs are available in the open repository: github.com/mshogin/archlint

The tool works with Go projects, but the approach is universal and applicable to any programming language.

The project includes:

Go code analyzer for building structural graphs
Tracing library for building behavioral graphs
Visualization generators (PlantUML, Mermaid)
CI/CD integration examples

Working with Chaos in Architecture

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

When you work with real systems, you quickly realize: most of the time you don’t start with a clean slate.

You start with history, compromises, half-implemented ideas, and changing priorities.

At first, it feels messy. But over time, you learn something important: clarity isn’t given - it’s created.

What working with chaotic architectures taught me

Listen before judging. Every decision was made in a certain context. Understanding that context is more important than rushing to conclusions.

Find patterns without forcing them. Patterns exist almost everywhere, but you need to let them emerge rather than forcing their appearance.

Build small anchors in unstable ground. When there’s a lot of uncertainty around, small steady steps are important.

And most importantly - stay patient with complexity. Complexity is not the enemy. It’s reality that you need to learn to work with.

Every messy system holds a story

And architecture, at its best, is about understanding that story and helping write the next chapter a little better.

If you’re also working in the middle of chaos: you’re not doing it wrong. Most likely, you’re exactly where real architecture starts.

Posts on Mikhail Shogin

AI Agent Linter Ecosystem: Quality, Cost and Safety Control

The Problem

The Pipeline

The Tools

archlint - Architecture Linter

promptlint - Complexity-Based Router

costlint - Token Cost Analysis

seclint / promptsec - Content Filter

Shared Principles

Numbers

Orchestration

Get Started

Links

Three blockers that prevent technical leaders from growing

Blocker 1: Territory defense

What it looks like

Why this is a blocker

The skill

Blocker 2: Craving recognition

What it looks like

Why this is a blocker

The skill

Blocker 3: The experience trap

What it looks like

Why this is a blocker

The skill

Three blockers. Three skills. None about technology

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

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

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

Cognitive debt опаснее technical debt

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

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

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

Workload creep

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

Будущее IDE

Итого

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Architect of Thinking

Результаты

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

После:

Что дальше

Spec-Driven Development: Controlling AI Code Generation

In this article

Observations

Hypothesis

Method

Storage Structure

Specification Sizes

S-Specification Example: Project Initialization

M-Specification Example: Collect Command

L-Specification Example: Go Code Analyzer

The Role of AI

Results

Specification Idempotency

Limitations

Conclusions

Structural and Behavioral Architecture: Graph-Based Approach to Complexity Control

Why Vibe Coding Doesn’t Work

Symptoms of Codebase Degradation

Stop and Understand

Structural Architecture: Static System Graph

Why a Formal Structure Model is Needed