Ai 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 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

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