Workflow 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

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.