Mikhail Shogin (Mike Shogin) - Systems Architect on Mikhail Shogin

Спека как живой контракт: SPDD, archlint и двусторонний sync

Wed, 29 Apr 2026 00:00:00 +0000

Симптом

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

Это не про дисциплину команды. Это про архитектуру процесса, в которой “спека” и “код” не имеют формальной связи.

Диагноз от Thoughtworks

28 апреля 2026 на сайте Мартина Фаулера вышла статья Structured Prompt-Driven Development от Wei Zhang и Jessie Xia. Они формулируют проблему точнее, чем я: “Local speed improves. But that doesn’t automatically translate into system-level throughput.”

Их предложение в трёх пунктах:

Промпт — это first-class артефакт. Версионируется, ревьюется, переиспользуется как код. Не реплика в чате.
REASONS Canvas — 7-частная структура промпта: Requirements, Entities, Approach, Structure, Operations, Norms, Safeguards. Первые четыре — абстракция, пятый — исполнение, последние два — governance.
Замкнутая петля между промптом и кодом с правилом, что обновлять первым:
- изменение поведения -> сначала промпт, потом код
- рефакторинг -> сначала код, потом sync обратно в промпт

Третий пункт — главное. Он превращает вечный спор “что source of truth” в процедуру.

Где это совпало с моей практикой

У меня уже был свой spec-driven workflow:

~/my/archlint/templates/specifications/spec-template.md — шаблон спеки с разделами Architecture, Requirements, Acceptance Criteria, Implementation Steps. Размерные градации XS/S/M/L/XL.
Правило в ~/.claude/rules/spec-workflow.md: “задача >30 минут или >3 шагов — обязательно спека до старта”.
Команда /ms-add-spec в Claude Code, которая генерирует спеку под задачу.
archlint — статический анализатор, который валидирует архитектурные правила (200+) на графе из AST.

REASONS Canvas почти один в один ложится на мой шаблон:

REASONS	Мой шаблон
R Requirements	## Requirements (FR1, FR2, …)
E Entities	## Architecture / Data Model (UML Class)
A Approach	## Overview / Solution Summary
S Structure	## Architecture / Component Overview (C4)
O Operations	## Implementation Steps
N Norms	(не было отдельного раздела)
S Safeguards	(не было отдельного раздела)

Совпадение на 70-80%. Архитектурный governance у меня вообще сильнее — archlint проверяет автоматически то, что в SPDD держится на ревьюере-человеке.

Где SPDD добавил то, чего не было

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

1. Спека “неизменна в процессе”

В моём spec-workflow.md буквально стояла формулировка:

Спека = ЧТО делать (неизменна в процессе)

Это противоположно идее живого артефакта. Спека написана, согласована, перенесена в inprogress/ — и потом никем не трогается, пока задача не закроется. На практике это значит, что любая правка реализации, отличающаяся от плана, проваливается между спекой и кодом.

2. Norms и Safeguards неявные

Стандарты команды (как именно мы оборачиваем ошибки, какой logger, какие naming-конвенции) у меня живут в куче .md файлов: ~/.claude/rules/architecture.md, проектные CLAUDE.md, в чате. На уровне отдельной спеки их явно никто не выносит. Авторы SPDD выделяют:

Norms — стандарты как принято писать. Часть автоматизирована (golangci-lint, archlint), часть нет.
Safeguards — неприкосновенные инварианты. Нарушение — стоп, не warning. Обратная совместимость, perf budgets, security boundaries.

Когда они в одной странице со спекой, тихий рефактор поперёк стандарта становится заметным на ревью.

Что я в итоге сделал

Два патча, оба сегодня.

Патч 1: `~/.claude/rules/spec-workflow.md`

Удалил “Спека неизменна”. Заменил на “Спека — живой контракт, синхронизирован с кодом всегда”. Добавил раздел “Двусторонняя синхронизация” с явным правилом prompt-first vs code-first:

1
2
3
4
5


Изменение поведения (publicly-exposed контракт, бизнес-логика, валидация)
-> сначала спека, потом код

Рефакторинг (поведение не меняется)
-> сначала код, потом sync обратно в спеку

И отдельный раздел “Norms и Safeguards: governance внутри спеки” с примерами и привязкой к archlint/golangci-lint.

Патч 2: `~/my/archlint/templates/specifications/spec-template.md`

Добавил две секции после Acceptance Criteria:

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


## Norms

- N1: error wrapping через fmt.Errorf("%w") или errtrace.Wrap
- N2: логирование через slog с контекстом
- N3: naming - DB snake_case, JSON camelCase

Автоматизировано:
- [ ] golangci-lint passes (errcheck, errorlint, sloglint)
- [ ] archlint passes (layered, fan-out, ISP)

## Safeguards

- S1: обратная совместимость публичного API в рамках minor релиза
- S2: p99 latency endpoint X не растёт более чем на 10%
- S3: нет утечки PII в логи и метрики

Проверка:
- [ ] Smoke test на обратную совместимость
- [ ] Бенчмарк до/после
- [ ] Аудит логов на чувствительные поля

Размерные градации те же: для XS Safeguards обычно не нужны, для M/L/XL — обязательны.

Что я НЕ взял

Не взял CLI openspdd и команду /spdd-prompt-update. Слишком много церемонии для одиночной работы и для команды без отдельного workflow-инженера. У меня та же дисциплина держится на:

/ms-add-spec — создать спеку
/ms-checkpoint — зафиксировать прогресс на длинной задаче
archlint — валидация Norms+Safeguards автоматически где можно
Code review через GitLab — двусторонний sync проверяется на ревью

Не взял правило “никогда не редактировать промпт руками”. У них это compensation за CLI-managed lifecycle. У меня его нет, и руками править .md спеку — нормальная операция.

Не взял заявление про “~99% intent alignment”. Это маркетинг, кейс N=1.

Двойная оптика

Технический слой статьи: дисциплина для AI-кодинга в команде.

Архитектура мышления за этим: проблема, которую решают авторы — не “AI пишет неправильный код”, а “bandwidth ревьюера не растёт со скоростью генератора”. Когда LLM выдаёт результат быстрее, чем человек успевает его понять, узкое место — когнитивная пропускная способность того, кто принимает изменения. SPDD сжимает то, на чём держится ревью, до одного артефакта (Canvas), чтобы он влезал в bandwidth.

Это та же задача, про которую я говорил на Стачке — контроль сложности через граф. Только на уровне процесса, а не статического анализа.

archlint = governance внутри кода (граф, правила, инварианты). SPDD/спека = governance над изменениями (контракт между намерением и реализацией).

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

Когда есть оба — каждый коммит проходит и через “не сломал ли архитектуру” (archlint), и через “соответствует ли намерению” (спека). На ревьюера падает только то, что обе автоматизации пропустили.

Ссылки

Оригинал статьи: Structured Prompt-Driven Development
openspdd (Thoughtworks-affiliated CLI): https://github.com/gszhangwei/open-spdd
archlint: https://github.com/mshogin/archlint

Совет умирает. Вопрос остаётся

Sat, 25 Apr 2026 00:00:00 +0000

Я 20 лет копил техническую экспертизу. За последние полтора года значительная её часть стала доступна любому, у кого есть подписка на нейросеть за 20 долларов.

Этот вопрос всплывает у меня периодически: насколько ценен мой опыт сегодня?

AI не “плохо отвечает”. AI поддерживает

Да, AI знает глубже, шире, точнее меня. И всё же есть особенность: AI поддерживает. Какое бы направление оператор ни выбрал - AI развивает именно выбранное.

Это даже не плохо. Молодой инженер с GPT движется в проблеме быстрее, чем я когда-то лопатил Stack Overflow и форумы по выходным.

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

Но смотрите дальше. Говорю AI: “Стоп. В моём прошлом проекте этот путь не сработал. Давай развернёмся”. Он отвечает: “Точно, отличная идея”. И теперь поддерживает развёрнутый вариант.

AI равно поддерживает любую мою сторону. И прежнюю, и развёрнутую.

И вот это - мой настоящий вопрос. На что опираться, если AI быстрее меня в ответах и подыгрывает любому моему выбору?

Поворот, которого я не ожидал

Ответ пришёл с неожиданной стороны: в этом году я учусь на коуча. Скоро экзамен ICF Level 1.

И эта учёба меня прижала.

Я всю жизнь работал в том же режиме, что AI. Только медленнее.

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

Человек кивает. Уходит.

Через неделю приходит снова. С тем же вопросом. В новой обёртке.

И я не понимал почему так.

Сейчас понимаю. Я отвечал на его слова. А не на его настоящий вопрос - который под словами: страх, сомнение, что-то очень его, во что мой совет даже не пытался попасть.

Что меняется

Учусь делать другое.

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

Это медленнее. Менее эффектно. И сложнее, чем выдать ответ за тридцать секунд.

Но самое интересное и самое сложное - дальше.

Когда у человека загорается лампочка - “Ага! Я понял!” - это не финиш. Это эмоциональный всплеск. Через два дня он рассасывается, и человек остаётся с тем же вопросом, что в начале.

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

Где мой компас

И вот тут связалось.

AI даёт ответы за секунды. Я давал ответы за минуты. Это - то, что заменяется.

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

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

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

Когда вам в последний раз помог не совет, а правильно поставленный вопрос?

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-агенту с файловой системой.

How to Onboard 4 Projects into Architectural Oversight Without Losing Your Mind

Tue, 03 Feb 2026 00:00:00 +0000

The Problem

Four projects simultaneously. Different teams, different stacks, unclear functional overlaps. “Figure it out” - the only instruction.

Classic situation: manager delegates, architect takes responsibility, but how to onboard projects systematically - unclear.

Questions:

Where to start?
What to check first?
How not to miss critical issues?
How many days will it take?

Keeping everything in your head is pointless. Need a process.

Symptoms of Chaos

When there’s no onboarding process, chaos begins.

Symptom 1: Archaeological Excavation

Architect spends a week searching for documentation. Slack, Confluence, Google Drive, wiki - information scattered everywhere. Half is outdated from a year ago. Half needs to be reconstructed from code.

Result: 5 days wasted.

Symptom 2: Unexpected Problems

A month after onboarding: monitoring doesn’t exist, tests don’t cover critical paths, CI/CD runs on workarounds. Too late to fix - project already in production.

Result: Firefighting instead of oversight.

Symptom 3: Team Conflicts

Architect starts changing code without context. Tech Lead resists: “We’ve been doing it this way for a year, why change?”

Result: Loss of trust.

Diagnosis: Need a System

Problem isn’t in projects. Problem is lack of process.

Project onboarding isn’t about code. It’s about:

Gathering context (business, technical, operational)
Assessing maturity (architecture, code, processes)
Aligning expectations (with PM, Tech Lead, team)
Improvement plan (prioritization and timeline)

Without a formal process, you reinvent the wheel every time.

Solution: 6-Phase Process

Studied industry practices (Futurice, TOGAF, Harvard EA) and assembled an onboarding process.

Process Phases

1
2


[Initiation] -> [Kickoff] -> [Info Gathering] -> [Audit] -> [Plan Agreement] -> [Onboarding]
 1 day 1-2 hours 3-5 days 3-7 days 1 day ongoing

Total time: 7-14 days.

Phase 1: Initiation (1 day)

Goal: Get basic information and access.

Actions:

Request intro from PM:
- What’s the project?
- What problems does it solve?
- Who’s the Tech Lead?
Request access:
- Repositories (GitHub/GitLab)
- Monitoring (Grafana/Prometheus)
- Documentation (Confluence/Notion)
- CI/CD (Jenkins/GitLab CI)
Schedule kickoff meeting.

Result: Basic project understanding, all access granted.

Phase 2: Kickoff (1-2 hours)

Goal: Sync with PM and Tech Lead.

Participants:

PM (business context)
Tech Lead (technical picture)
Architect (onboarding)

Agenda:

Business context (10 min)
- Why this project?
- Who are the users?
- What are success metrics?
Technical picture (30 min)
- Architecture (components, integrations)
- Stack (languages, frameworks)
- Operations (deployment, monitoring, incidents)
Oversight expectations (20 min)
- What’s needed from architect?
- How often syncs?
- Code review/Design review?
Next steps (10 min)
- Documentation gathering
- Audit dates
- Report format

Result: Everyone aligned, plan agreed.

Phase 3: Information Gathering (3-5 days)

Goal: Collect everything needed for audit.

What we gather:

1. Documentation

Architecture (C4, ADR)
API specs (OpenAPI/Swagger)
Business processes (BPMN)
Incidents (postmortems)

2. Code

Repo structure
Test coverage
Code quality (linters, code review)

3. Infrastructure

CI/CD pipeline
Deployment (Kubernetes/Docker)
Monitoring (metrics, alerts)
Logs (structured, retention)

4. Operational

SLA (uptime, latency)
Incident history
Escalation processes

Result: Folder with materials for audit.

Gathering checklist:

1
2
3
4
5
6
7
8


- [ ] Architecture documentation (C4, ADR)
- [ ] API specifications (OpenAPI)
- [ ] Database schema (ER-diagram)
- [ ] CI/CD pipeline (configs)
- [ ] Monitoring (Grafana dashboards)
- [ ] Incident history (postmortems)
- [ ] Test coverage (coverage report)
- [ ] Team processes (code review, standup)

Phase 4: Audit (3-7 days)

Goal: Understand current project state.

Audit levels:

Level 1: Architecture Overview (1-2 days)

System structure (components, layers)
Bounded contexts (if microservices)
Integrations (sync/async)
Tech debt map

Level 2: Deep Dive (2-4 days)

Code (smells, complexity, duplicates)
Tests (coverage, quality, fragility)
CI/CD (speed, reliability, rollback)
Monitoring (completeness, alerting, observability)

Level 3: Operational (1 day)

SLA vs actual
Incidents (frequency, recovery time)
Team processes (code review, ADR, standups)

Audit tools:

I assembled an audit template together with Claude Code (~3882 lines of config). Read and edited it.

What resulted:

Checklist (11 sections, 80+ items)
Report template (12 sections)
Automated validation (215 metrics)

Validation example:

1
2
3
4
5
6
7
8
9


# Test coverage check
$ archlint validate --template system-audit --project ./my-project

✓ Test coverage: 78% (target: >70%)
✗ Critical paths coverage: 45% (target: >80%)
✓ CI/CD pipeline: green
⚠ Monitoring: missing SLO alerts

Score: 7/10 (acceptable with improvements)

Audit result:

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


# Audit Report for {ProjectName}

Date: YYYY-MM-DD
Architect: {Name}

## Executive Summary
- Status: Acceptable with improvements
- Critical issues: 3
- Needs attention: 12
- Score: 7/10

## Critical Issues (P0)
1. No SLO monitoring
2. Critical path coverage <50%
3. Missing ADR process

## Needs Attention (P1)
...

## Recommendations
...

Phase 5: Improvement Plan Agreement (1 day)

Goal: Agree on action plan with team.

Format: Meeting with PM and Tech Lead (1 hour).

Agenda:

Report presentation (30 min)
Critical issues discussion (20 min)
Improvement plan (10 min)

Three plan types depending on state:

Plan 1: Stable Project

Non-critical issues
Quarterly improvement plan
Focus: development and optimization

Plan 2: Quick Fixes Needed

Critical issues present
Fix plan: 2-4 weeks (priority)
Then quarterly improvement plan

Plan 3: Stabilization Required

Multiple critical issues
Stabilization plan: 1-3 months
Oversight in firefighting mode
After stabilization - transition to development

Result: Agreed action plan with priorities and timelines.

Phase 6: Onboarding (ongoing)

Goal: Integrate into team.

Actions:

Join communications:
- Slack/Teams channels
- Standups
- Retros
Set up regular touchpoints:
- Weekly sync with Tech Lead (30 min)
- Design review (on demand)
- ADR review (as created)
Define control points:
- Code review of critical changes
- ADR approval
- Pre-release review

Result: Architect integrated into team.

Process Artifacts

Formalized the entire process as templates.

What I created:

Onboarding process (6 phases)
- Each phase description
- Time frames
- Communication templates
Onboarding checklist (11 sections, 80+ items)
- Business context
- System analysis
- Architecture
- Code and tests
- CI/CD
- Monitoring
- …
Audit template (12 sections)
- Report structure
- Evaluation criteria
- Recommendations format
Automated validation (215 metrics)
- Checklist verification
- Scoring (1-10)
- Automatic report

Where to look:

Onboarding process: github.com/mshogin/archlint/templates/project-handover
System audit: github.com/mshogin/archlint/templates/system-audit

Success Metrics

How to know the process works?

Metric 1: Onboarding time

Target: < 2 weeks
Measure: from initiation to onboarding
Why important: quick oversight start

Metric 2: Critical issues closure

Target: > 80% per quarter
Measure: percent of closed P0 from report
Why important: real quality impact

Metric 3: Tech Lead satisfaction

Target: > 4/5
Measure: survey after 3 months oversight
Why important: team trust

Metric 4: Design review participation

Target: > 90%
Measure: percent of reviews architect participated in
Why important: process involvement

Usage Example

Theory so far. Next week I start onboarding 4 projects - let’s see what breaks in reality.

Plan:

Week 1: Initiation + kickoff for all 4 projects
Weeks 2-3: Information gathering and audit (parallel)
Week 4: Decision + onboarding

Will track:

Where process got stuck
Which checklist items were useless
How long each phase took
What problems weren’t detected

After completion - will write second article with real experience and gotchas.

Summary

What’s done:

6-phase onboarding process (7-14 days)
Checklist (11 sections, 80+ items)
Audit template (12 sections)
Automated validation (215 metrics)

Why it matters:

Systematic approach instead of chaos
Reproducible process
Control of critical aspects
Measurable success metrics

What’s next:

Test on 4 projects
Gather feedback
Improve process
Write second article with real experience

How do you onboard projects? And do you use AI for audits?

AI Doesn't Replace - AI Changes the Role

Mon, 19 Jan 2026 00:00:00 +0000

Recently stumbled upon a stat: 55% of companies that laid off people because of AI now regret it. And a METR study showed something weird - developers think they work 20% faster with AI, but actually turned out to be 19% slower.

Then I read Hinton saying that in a couple years AI will do in minutes what takes an engineer a month. And AWS CEO responds calling the refusal to hire juniors “one of the dumbest things I’ve heard.”

So who’s right?

My experience says - both are wrong. AI doesn’t replace people. And it doesn’t slow work down. It just changes what we do.

What I’ve Given to AI

Honestly - almost all analytics. Draft diagrams, text editing, searching and analyzing information. I’ve practically stopped coding by hand - always work with an agent now. Need some expertise - AI is my first stop.

Sounds like I’ve given everything away. But no.

What I Won’t Give Up

Health. This is clear for me. I don’t mind if a doctor uses AI - actually, that’s good. But it should be a doctor. With education. With experience. AI as a tool - yes. AI instead of a doctor - no.

Same with a psychologist. I like working with a real person, and I don’t see how that can be replaced. Same with a coach.

Everything related to my health, consciousness, awareness - only to professionals. Who can use AI in their work, but professionals nonetheless.

About This “Productivity Paradox”

That METR study got me thinking. People think they’re faster, but actually slower. A paradox, they say.

I disagree.

How did it used to work? You could try one or two implementation options. Picked something, went ahead. Hit problems - made a third version. Then fourth. And it all piled up. First version lying around somewhere, second, third - and you’re already on the fifth, dragging legacy behind.

Now I try a bunch of options at once in the same time. Yes, each specific option takes more time. But I’m not dragging three failed attempts behind me. I pick the best option before I start burying it in production.

That’s not slowing down. That’s a different way of working.

Juniors

AWS CEO put it well: “How’s that going to work ten years from now when nobody’s learned anything?”

Completely agree. There has to be knowledge transfer. Generational turnover of specialists.

Yes, with AI you can make websites and telegram bots without much education. But the industry isn’t just websites and bots. There’s tons of stuff that needs higher math. That needs computer science. Juniors are needed. And they need to be trained.

How My Role Has Changed

Writing code by hand - no point anymore. Now I think about architecture. Design systems. Do reviews. Validate what came out.

And the design itself is also with AI - you talk to the agent, break down the task. Then hand it off for implementation and check the result.

Basically, the role has shifted. Before - executor. Now - designer and validator.

What’s Become More Important

Systematic approach. These stories about the “hero developer” who fixed everything at night, or the “firefighter” who’s everywhere at once - that’s going away. People who solve problems systematically are valued.

And another skill has emerged: building your own system for working with AI. Just dictating a prompt - doesn’t work. You need an actual system. Your own prompts, rules, skills, agents.

I spend time not just on work tasks, but on this system. It’s my asset. My intellectual property, if you will.

What’s the Point

AI doesn’t replace specialists. It changes what they do.

55% of companies regret layoffs not because AI doesn’t work. But because they didn’t understand - people’s role has changed, not disappeared.

Less execution, more design. Less heroics, more system. Less hand-coding, more work on your own tools.

That’s how it looks right now. At least for me.

More on AI in development and architecture: Telegram

$HOME in Git: One Config for Claude Code

Fri, 09 Jan 2026 00:00:00 +0000

Multiple projects. Each with its own CLAUDE.md, its own rules. You improve something in one place - you want it elsewhere. Copy. Improve there. Copy back. Round and round.

At some point I had a mess of different versions of the same rules scattered across a dozen projects. The copy-paste circus was annoying, but I kept putting it off.

During the New Year holidays, I decided to fix it.

The Solution

Moved everything to my home directory ~/.claude/. One config for all projects.

Yes, I’m now coupled to my home directory structure. But that structure hasn’t changed in years - ~/my/ for projects, ~/education/ for learning, ~/family/ for family stuff. Risk is minimal.

Structure

 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


~/.claude/
 CLAUDE.md # Core principles (task confirmation, formatting)
 HOME_MAP.md # Home directory map for navigation

 rules/ # Rules (auto-loaded)
 architecture.md # Architecture principles
 coaching-layer.md # Coaching questions
 text-dna.md # Writing style
 home-navigation.md # Context detection by keywords
 projects/ # Project-specific rules
 aitrader.md # Rules for aitrader

 commands/ # Slash commands
 ms-todos.md # /ms-todos - task list
 ms-add-note.md # /ms-add-note - add note
 ...

 skills/ # Skills
 blog-writing/ # Blog post writing
 go-review/ # Go code review
 social-content/ # Social media content

 agents/ # Custom agents
 go-reviewer.md # Go code reviewer

 hooks/ # Hooks
 session-logger.py # Session logging

The key file is HOME_MAP.md. It’s a map of the entire home directory with context detection rules.

Claude sees keywords in your request and knows which directory to work in:

aitrader, archlint, blog -> ~/my/
course, book, learning -> ~/education/
memory, remember, mission -> ~/my/org-roam/

If context is ambiguous - it asks.

Project-Specific Rules

Need specific rules for a project? Add them to rules/projects/. For example, aitrader.md contains:

How to run the collector (without proxy for Tinkoff API)
Test commands
Project specifics

These rules load globally but apply only when working in the aitrader context.

Git

Everything under git. One repository, one history.

.gitignore is large - it excludes almost everything that shouldn’t be versioned: credentials, caches, Downloads, Documents, Library, .ssh. But everything else - configs, .claude/, dotfiles - is tracked. Planning to add private repos as submodules, so one git clone restores the entire home directory.

No more copying between projects. Improve a rule once - it works everywhere.

Result

Before: a dozen projects with scattered CLAUDE.md files, constant copying, different versions of the same thing.

After: one ~/.claude/, structured rules, git for versioning. Improve once - works everywhere.

Downside: tight coupling to home directory structure. For me it’s not a problem - the structure is stable.

Spec-driven development: Reproduce a project from specs alone

Mon, 05 Jan 2026 00:00:00 +0000

Ran an experiment: can you reproduce a project if you give AI only specifications without source code?

Setup

Original project: archlint - a Go architecture analysis tool
Input: 10 specifications (Markdown + PlantUML), totaling 73 KB.
Claude Code received an empty directory and specs
Executor: Claude Code, started in an empty directory and implemented the project from scratch.

Specs covered all the basics: module init, Makefile, data model, Go-analyzer, Cobra CLI, collect/trace commands, tracer library, tracelint, and integration tests.

Time

~20 minutes from empty directory to working project.

Results

Final assessment of the cloned repository:

Structural identity: 100%
Cloning success: 85.5%
Semantic equivalence: ~75%
Mutations: 23 (3 critical, 8 medium, 12 minor)

Interesting detail: the clone turned out shorter than the original - 1,845 lines of Go vs 2,159 (-14.5%) with the same number of .go files (13).

Mutations that actually matter

Three “critical” mutations - exactly the places where the specification leaves room for interpretation (i.e., for creativity you didn’t order):

Sequence diagram building: changed the algorithm for forming calls in the diagram (logic for call stack and write conditions).
Tracerlint: clone considers deprecated Exit() call acceptable, while the original does not.
GoAnalyzer: added baseDir and modulePath fields - AI “improved” the model because the specs didn’t explicitly define the analyzer’s responsibility boundary (what to store inside, what to compute outside).

Takeaway

Spec-driven development works as a mechanism for reproducing the “functional core”. 73 KB of specifications was enough to quickly restore structure and core functionality.
Critical deviations occur where the specification describes “what should be” but doesn’t define “how to verify it”. For such places you need:
- precise rules (invariants),
- input/output examples,
- golden tests (byte-by-byte/structural comparison),
- prohibition on “model extension” without an explicit spec item.

In short: AI can clone a project from specs quickly. But if there’s a gap in the specs - it will definitely squeeze in some “engineering optimization”. Sometimes useful. In critical places - usually not.

Clone repository: mshogin/archlint-reproduction

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

Mikhail Shogin - About

Mon, 01 Dec 2025 00:00:00 +0000

I’m doing software development since 2004. From that time, I’ve done several projects, participated in another number of teams and played with many different technologies, programming languages and frameworks.

Currently I work at Wildberries & Russ as Systems Architect in the platform employment domain. I oversee the financial perimeter: write-offs, penalties, disputes, and loss control.

In parallel, I develop practices for architectural oversight, system analysis, and business analysis. My focus is on automating these processes and integrating AI tools into team workflows.

Before that - IPONWEB (later acquired by Criteo), where I grew from Perl/Lua developer to Systems Architect of Commerce Grid.

Over these years I developed a simple algorithm - three questions before any task:

Goal: what do I want to achieve?
Reality: what do I know and don’t know?
Action: what will I do right now?

Experience

WBJob - Architecture - Wildberries & Russ

Building system analysis, business analysis and architecture into the development process. Together with a fellow architect and a team of analysts, we establish standards and integrate into processes.

Main challenge: embed three stages (business analysis, system analysis, architectural oversight) into the development process without increasing time-to-market.

HRTech - digital transformation - Wildberries

Joined Wildberries as Systems Architect and built HR Tech as a manageable engineering system: system analysis practice, architecture as code, transparent integrations and delivery quality - instead of “we agreed verbally and shipped”.

What I built as organizational-architectural foundation:

Built system analysis department from scratch: assembled the team, established the practice, and embedded system analysis into the development process (requirements elaboration, contracts, integration coordination, acceptance criteria).
Implemented “Architecture as Code” approach: documented services and their responsibilities, captured key decisions through ADRs, built a service map and dependencies as a maintainable artifact, not “knowledge in heads”.
Brought order to integrations: consolidated chaotic “verbal” integrations and manual token provisioning into a formalized approach - with a unified integration service, rules, automation and traceability.
Introduced testing culture: launched testing practices where none existed, integrated checks into CI/CD pipeline, improved release predictability and change quality.
Drove major initiatives to completion: took on large changes, drove them through teams and dependent stakeholders, closed “loose ends” rather than leaving them as eternal concepts.

Key product domains:

HR Platform (HRPortal) - single source of truth for employees (warehouse + office/IT).
ATS (Applicant Tracking System) - recruiting and onboarding, reducing dependency on external provider (HeadFlow).
Team Management (WBTeam) - team management: vacancy requests, notifications, approvals.
Compensation & Benefits (C&B) - calculation automation, tariffication and financial risk control.

Internal Control & Audit - SKU logistics - Wildberries & Russ

Accumulated SKU cost:

Architectural support for the system calculating accumulated service cost per item (SKU) across the entire Wildberries logistics chain: gate acceptance -> warehouse -> transport logistics -> pickup points. Each major stage consists of multiple processes, each adding operation cost. Understanding this picture provides a foundation for optimization - from individual operations to major processes (sorting, acceptance, last mile).

Warehouse operations tariffication:

Architectural support for the tariffication system. Specifics: all operations (warehouse + transport) are tariffed and paid - hourly, per operation, various output schemes. Enormous number of rules, nuances and legacy. Main constraint: warehouse must always operate, downtime is unacceptable.

Commerce Grid - platform architecture - Criteo

After IPONWEB was acquired by Criteo, I joined as Systems Architect to work on Commerce Grid - a retail media platform.

My key contributions:

Created the initial C-Grid architecture model and established collaborative architecture practices
Led Kubernetes migration for critical services with minimal downtime
Built integration testing environment with Docker-based infrastructure for local development and CI
Implemented service mesh, monitoring, and observability solutions
Established architecture review processes and cross-team collaboration

The platform enables retailers to monetize their digital properties through advertising while maintaining user experience and data privacy.

DevOps & SRE - diving into operations - Criteo

Working as a developer, I often heard from devops: “this takes long”. Got curious - what takes so long? Dove into DevOps for a year and a half, fully focused on infrastructure tasks. Then heard the same from SRE - “complex, takes time”. Moved to SRE for another year.

Figured out how it all works from the inside: Google Cloud, AWS, Terraform, CI/CD pipelines. Now I understand both sides - development and operations.

BidCast - Load Balancer development - IPONWEB

One of the most complex projects. Two goals: decompose the BidSwitch monolith and test a hypothesis - can we build our own load balancer cheaper than Google/AWS.

First version proved: our load balancer is cheaper to maintain. Then we started moving logic from BidSwitch to BidCast - everything not tied to state and database, offloading heavy code.

Main achievement - AdTXT module: developed my own data storage format that allowed loading 5-6 GB into process memory in ~1 second and searching in 10 nanoseconds. This enabled extracting functionality from BidSwitch and saving tens of thousands of dollars per month. BidCast didn’t even notice the new module performance-wise.

BidSwitch - monolith decomposition to microservices - IPONWEB

Microservices were at peak popularity back then. Led the decomposition of BidSwitch monolith into microservices - created about 7 services behind an API Gateway.

How it ended: shut down the initiative. Microservices support turned out more expensive than monolith - need to grow teams, more people. With monolith one team ships features, maybe slower, but steadily.

What I gained: lots of practices, hard-learned lessons, deep understanding of tradeoffs. Main microservices benefit - ability to completely rewrite a service in 1-2 weeks. Can’t do that with a monolith.

uWorkflow - Django monolith - IPONWEB

Django monolith designed like a LEGO constructor - lots of small components. The system configured itself on the fly from a given schema. Configuration driven development: managing objects and relations through OpenAPI-compatible schemas. Schema was the heart of the system.

Result:

Faster project delivery
All code in one repository
Small team supporting many projects

Became experts in Python, Django and DRF.

Spent two years traveling across Myanmar, Thailand, Laos, Vietnam, Cambodia, Malaysia, Indonesia, the Philippines, Nepal, India, and Sri Lanka.

During this time, I focused on deep self-learning and skill-building:

Learned Python and built a small social network for pet owners
Studied PostgreSQL and understood how to model and query structured data
Switched fully to Emacs, building my own productive workflows
Taught myself blind typing in English - to code and write faster
Developed clarity, focus, and the ability to learn independently - skills I rely on every day in architecture and engineering

This journey shaped not only how I live, but how I think.

Рассылки - email marketing - Mail.Ru

30-40 million personalized emails per day. Two main challenges: Mail sender and Targeting machine.

Mail sender in Perl with event loop. Hardcore times: daemons, interprocess communication, sockets, synchronization.

Targeting machine - first AdTech experience. Personalized targeting for each email. Developed a data structure with custom hash function: checking all variants in O(1). AdCache was huge but worked super fast.

Learned TDD on this project - been writing tests for all my code ever since.

Mission

Helping companies transform complex systems into manageable architecture with clear boundaries, reliable integrations, and predictable evolution.

This isn’t about beautiful diagrams or trendy frameworks. It’s about:

Developers understanding where their responsibility ends
Changes in one service not breaking ten others
New team members being able to understand the system in days, not months
Business being able to plan development knowing the real cost of changes

Complexity is inevitable. Chaos is not.

Values

Clear boundaries of responsibility

Each component knows its zone and doesn’t intrude on others. When boundaries are blurred, any change becomes an archaeological dig - who uses this? who will this break?

Contracts over verbal agreements

If an integration isn’t formally described, it doesn’t exist. API contracts, data schemas, SLAs - everything must be documented. “We agreed on this during a call” is not a contract.

Measurable outcomes

If you can’t measure it, you can’t improve it. Architecture metrics, test coverage, response time, coupling between modules - everything should be a number, not a feeling.

Reliability by default

The system should work predictably, not “usually works”. Graceful degradation, retry policies, circuit breakers - not options, but baseline requirements.

Simplicity and evolvability

Complexity grows only when truly necessary. Every abstraction must justify its existence. Three similar lines of code are better than a premature abstraction.

Philosophy

70/30 approach

Conservative-risk-oriented balance. 70% of decisions use proven, reliable approaches. 30% are controlled experiments with new technologies and methods.

I work only with manageable risks. This means:

Clear criteria for success and failure
Rollback plan before starting changes
Isolation of experiments from critical paths

Context over templates

Good architecture starts with understanding context, not applying ready-made solutions. Each system is unique and requires its own approach.

“Best practices” are someone else’s experience in someone else’s context. Useful to know, dangerous to copy blindly.

Explicit boundaries of responsibility

Not just in code, but in processes. Who makes the decision? Who bears responsibility for consequences? Who has veto power?

Blurred boundaries are a source of conflicts and decision paralysis.

Places I’ve been

Actually to remember all the places I’ve been is very difficult task and only my wife is able to help me with it. Thank you dear, I love you!

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.

Mon, 01 Jan 0001 00:00:00 +0000

Принял 4 проекта в надзор: делюсь процессом приёмки и аудита

TL;DR

Руководитель дал 4 новых проекта в архитектурный надзор. Держать всё в голове нереально. Изучил индустриальные практики и подготовил процесс приёмки совместно с Claude Code. Выложил в open-source. Буду рад feedback от вас и ваших агентов.

Как всё началось

Руководитель: “Вот тебе 4 проекта - принимай в работу.”

Я: “Окей… А что там?”

Руководитель: “Узнаешь.”

Контест:

4 проекта
Где-то есть пересечение функциональности (где именно - неясно)
Команды разные, стек разный, зрелость разная
Держать всё это в голове - бесмысленно

Немного поглядел - стало понятно: нужен системный подход.

Что я сделал

1. Изучил индустриальные практики

Посмотрел, как это делают:

Futurice Project Handover Checklist
TOGAF Architecture Review
Harvard EA Checklist
Практики из книг (Software Architecture in Practice, Building Evolutionary Architectures)

2. Собрал процесс приёмки и аудита

Готовил совместно с Claude Code. Не в чистом виде, конечно - с моей конфигурацией (на текущий момент это 3882 строк rules, skills and commands). Безусловно, вычитывал и редактировал.

Что получилось:

Процесс приёмки проекта

6 фаз:

Инициация (получить вводную, доступы)
Kickoff встреча (PM + Tech Lead)
Сбор информации (документация, код, мониторинг)
Аудит (анализ архитектуры)
Решение о приёмке (принят/с оговорками/не принят)
Онбординг в надзор (регулярные встречи, точки контроля)

Файлы:

project-handover-process.md - детальный процесс
project-handover.md - чеклист (11 секций, 80+ пунктов)

Шаблоны аудита системы

Ручной аудит (12 разделов):

Структура системы (C4, bounded contexts)
Взаимодействие сервисов (sync/async, матрица зависимостей)
Паттерны и антипаттерны
Observability (метрики, логи, трейсинг, алерты)
Устойчивость (SPOF, graceful degradation, DR)
Безопасность
План улучшений

Автоматическая валидация (215 метрик):

Coupling и fan-out
Layer violations
God classes
Циклические зависимости
Топологические метрики

Файлы:

system-audit.md - ручной аудит
audit.md - отчет автоматической валидации

3. Статус

На следующей неделе начинаю приёмку. Посмотрим как процесс сработает в реальности.

Если эксперимент удастся - расскажу подробнее о результатах, подводных камнях и корректировках процесса.

Вопрос к сообществу

Буду рад feedback от вас и ваших агентов:

Процесс: Что лишнее? Чего не хватает?
Чеклисты: Какие критичные пункты я упустил?
Автоматизация: Используете ли инструменты для валидации архитектуры?
Агенты: Если вы используете AI-агентов для аудита - какие задачи им даёте? Как проверяете результаты?

Open-source шаблоны:

Project Handover - процесс и чеклист приёмки
System Audit - ручной и автоматический аудит
Specifications - spec-driven development
ADR - Architecture Decision Records

С удовольствием улучшу на основе вашего опыта.

UPD: Если интересно как процесс сработал на практике - подписывайтесь, расскажу после завершения приёмки. Telegram: https://t.me/MikeShogin

#архитектура #процессы #opensource #claudecode

Mon, 01 Jan 0001 00:00:00 +0000

Материалы для публикации: Project Handover Templates

Посты о процессе приёмки проектов в архитектурное курирование.

Файлы

telegram-post.md - пост для Telegram канала @MikeShogin
habr-post.md - статья для Habr

Статус

Шаблоны созданы и структурированы в archlint/templates
Посты подготовлены
Опубликовано в Telegram
Опубликовано на Habr
Большая статья для mshogin.ru (опционально, после приёмки проектов)

Ссылки на шаблоны

План

Опубликовать короткие посты (Telegram + Habr)
Начать приёмку проектов на следующей неделе
После завершения приёмки - написать большую статью с реальным опытом и подводными камнями
Обновить шаблоны на основе практики

Пост для Telegram

Как принять 4 проекта в курирование и не свихнуться?

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

Я быстро осознал: вручную я это не вывезу. Чтобы спасти ситуацию, я решил опереться на индустриальные стандарты (Futurice, TOGAF, Harvard EA) и собрать системный процесс приёмки и аудита.

Что мы разработали вместе с Claude Code:

Процесс приёмки (6 фаз)
Чеклист (11 секций, 80+ пунктов)
Шаблон аудита (12 разделов)
Автоматическая валидация (215 метрик)

Это была плотная работа.

Пока теория. На следующей неделе начинаю приёмку - посмотрим что сломается в реальности.

Ознакомиться можно здесь:

Процесс приёмки: https://github.com/mshogin/archlint/tree/main/templates/project-handover
Аудит систем: https://github.com/mshogin/archlint/tree/main/templates/system-audit

Как вы принимаете проекты? И юзаете ли AI для аудита?

С удовольствием улучшу.

#архитектура #systemaudit #claudecode

Contacts

Mon, 01 Jan 0001 00:00:00 +0000

Telegram: @MikeShogin
GitHub: mshogin
LinkedIn: mshogin

Business Details

Individual Entrepreneur Shogin Mikhail Mikhailovich

Registration Number (OGRN): 323508100081596
Tax ID (INN): 504416750702

Ecosystem

Mon, 01 Jan 0001 00:00:00 +0000

GenieArchi - AI Agent Linter Ecosystem

Quality, cost, and safety control for AI agent workflows. All Go + Rust, no LLM, under 10ms.

Pipeline

1

prompt -> seclint (safety) -> promptlint (routing) -> agent -> archlint (quality) -> costlint (cost)

Tools

Tool	Purpose	Repo
archlint	Architecture linter - SOLID violations, cycles, fan-out	mshogin/archlint
promptlint	Prompt complexity scoring, model routing	mikeshogin/promptlint
costlint	Token cost analysis, caching, A/B tests	mikeshogin/costlint
seclint	Content filter, age ratings (6+/12+/16+/18+)	mikeshogin/seclint
GenieArchi	Umbrella project	mikeshogin/geniearchi

Numbers

58% cost savings through intelligent routing
Under 10ms per analysis
Go + Rust (archlint-rs: single binary)

Services

Architecture Audit - scan your project, find violations, get report
Cost Optimization - route simple tasks to cheap models
PR Architecture Review - automated arch diff on every PR
Agent Ecosystem Setup - full pipeline in days

Partners

Project	Purpose
myhome	Workspace management
deskd	Agent runtime (Rust)
nassau	Governance rules

Events

Mon, 01 Jan 0001 00:00:00 +0000

Upcoming Events

Event	Description	Date
Why Data Catalog Brings No Value	Free online webinar about typical data catalog implementation mistakes and how AI can transform documentation workflows. Speaker: Pavel Khamrin.	February 10, 2026, 11:00 AM MSK

Notes

Mon, 01 Jan 0001 00:00:00 +0000

Resources

Mon, 01 Jan 0001 00:00:00 +0000

Personal Blogs

Author	Description	Links
Mikhail Shogin	Systems Architect at Wildberries & Russ. Working with real systems, helping find patterns where there seems to be only chaos. Experience: Wildberries, Criteo, IPONWEB, Mail.Ru.	Telegram, Website
Sergey Baranov	Architect, producer of ArchDays conference	Telegram, Website

Telegram Channels

Channel	Description
@emacsway_log	Software Design, Clean Architecture, DDD, Microservice Architecture, Distributed Systems, Extreme Programming, SDLC, Agile
@it_arch	Discussions about enterprise information systems architecture (enterprise architecture, IT solutions architecture)
@plant_uml	Discussing PlantUML
@dochubchannel	Architecture as Code approach and DocHub tool. Website, GitHub, Examples
@analyst_job	Job postings and resumes for analysts

Websites

Name	Description
dckms - System Architecture	Materials on system architecture
ArchDays	Conference for architects

Search

Mon, 01 Jan 0001 00:00:00 +0000

Mikhail Shogin (Mike Shogin) - Systems Architect on Mikhail Shogin

Спека как живой контракт: SPDD, archlint и двусторонний sync

Симптом

Диагноз от Thoughtworks

Где это совпало с моей практикой

Где SPDD добавил то, чего не было

1. Спека “неизменна в процессе”

2. Norms и Safeguards неявные

Что я в итоге сделал

Патч 1: ~/.claude/rules/spec-workflow.md

Патч 2: ~/my/archlint/templates/specifications/spec-template.md

Что я НЕ взял

Двойная оптика

Ссылки

Совет умирает. Вопрос остаётся

AI не “плохо отвечает”. AI поддерживает

Поворот, которого я не ожидал

Что меняется

Где мой компас

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

Результаты

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

После:

Что дальше

How to Onboard 4 Projects into Architectural Oversight Without Losing Your Mind

The Problem

Symptoms of Chaos

Патч 1: `~/.claude/rules/spec-workflow.md`

Патч 2: `~/my/archlint/templates/specifications/spec-template.md`