Architecture on Mikhail Shogin

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

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 даёт ответы за секунды. Я давал ответы за минуты. Это - то, что заменяется.

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

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

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

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

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?

Spec-Driven Development: Controlling AI Code Generation

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

Observations

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

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

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

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

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

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

Hypothesis

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

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

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

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

Method

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

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

Storage Structure

Kanban-like organization via file system:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


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

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

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

Specification Sizes

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

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

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

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

S-Specification Example: Project Initialization

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


# Spec 0001: Initialize Standard Golang Project Layout

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

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

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

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

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

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

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

M-Specification Example: Collect Command

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

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


# Spec 0006: Implement Collect Command

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

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

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

## Architecture
### Sequence Flow (PlantUML)

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


title Sequence: Collect Command

actor User
participant "collectCmd" as CC
participant "GoAnalyzer" as GA
participant "saveGraph" as SG

User -> CC: archlint collect . -o arch.yaml
CC -> GA: Analyze(dir)
GA --> CC: *Graph
CC -> SG: saveGraph(graph)
SG --> CC: nil
CC --> User: "Graph saved to arch.yaml"

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


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

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

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

Sequence diagram defines call order. AI follows it literally.

L-Specification Example: Go Code Analyzer

Large tasks require multiple diagrams - Data Model and Sequence:

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


# Spec 0004: Implement Go Code Analyzer

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

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

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

## Architecture
### Data Model

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


class GoAnalyzer {
 -packages: map[string]*PackageInfo
 -types: map[string]*TypeInfo
 -functions: map[string]*FunctionInfo
 -nodes: []model.Node
 -edges: []model.Edge
 --
 +NewGoAnalyzer() *GoAnalyzer
 +Analyze(dir string) (*model.Graph, error)
 -parseFile(filename string) error
 -buildGraph()
}

class PackageInfo {
 +Name: string
 +Path: string
 +Imports: []string
}

class TypeInfo {
 +Name: string
 +Package: string
 +Kind: string
 +Fields: []FieldInfo
}

GoAnalyzer "1" *-- "*" PackageInfo
GoAnalyzer "1" *-- "*" TypeInfo

1

### Sequence Diagram

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


title Sequence: Code Analysis

actor User
participant "GoAnalyzer" as GA
participant "go/parser" as GP
participant "buildGraph" as BG

User -> GA: Analyze(dir)
loop For each .go file
 GA -> GP: ParseFile(filename)
 GP --> GA: *ast.File
 GA -> GA: Extract packages, types, functions
end
GA -> BG: buildGraph()
BG --> GA: *Graph
GA --> User: *Graph, nil

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


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

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

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

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

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

The Role of AI

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

The agent has two areas of responsibility.

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

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

Results

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

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

Result in 20 minutes:

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

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

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

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

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

Specification Idempotency

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

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

The trade-off is obvious:

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

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

Limitations

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

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

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

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

Conclusions

The hypothesis was confirmed:

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

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

The experiment continues.

Templates and examples: github.com/mshogin/archlint

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

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

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

Why Vibe Coding Doesn’t Work

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

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

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

Symptoms of Codebase Degradation

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

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

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


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

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

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

Digging deeper, I found:

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

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

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

Stop and Understand

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

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

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

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

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

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

Structural Architecture: Static System Graph

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

Why a Formal Structure Model is Needed

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

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

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

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

Graph as a Formal Model

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

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

Each node v ∈ V has:

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

Each edge e ∈ E has:

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

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

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

Real Example: archlint Architecture

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

Package Level (8 packages):

1
2
3
4
5
6
7
8


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

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

Data Types:

Data types are organized by domains:

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


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

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

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

Functions:

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

1
2
3
4
5


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

Connections Between Components:

The connection graph shows dependencies between packages and data types:

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

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

Automatic Graph Building from Source Code

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

Building the structural graph happens in four stages:

Stage 1: Source Code Analysis

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

1

$ archlint collect . -o architecture.yaml

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

Analysis result:

1
2
3
4
5
6
7
8
9


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

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

Stage 2: Graph Node Formation

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

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


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

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

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

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

Stage 3: Graph Edge Formation

We create edges expressing connection semantics between components:

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


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

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

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

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

Different edge types allow distinguishing connection semantics:

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

Stage 4: Saving in YAML Format

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

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

Validated: Check architectural rules. For example:

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

Analyzed: Compute metrics:

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

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

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

Behavioral Architecture: Dynamic Execution Graph

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

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

Why Behavioral Architecture is Needed

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

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

Behavioral architecture is critically important for:

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

How Acceptance Tests Form Behavioral Architecture

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

The “one task - one acceptance test” principle:

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

For example:

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

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

Behavioral graph building process:

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

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

Real Example: “Calculate With Trace” Context

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

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


func TestCalculateWithTrace(t *testing.T) {
 // Create directory for traces
 traceDir := "traces"
 os.MkdirAll(traceDir, 0755)

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

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

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

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

Code Instrumentation:

All system functions contain instrumentation points:

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


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

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

 sum := Add(a, b) // trace will record the call
 product := Multiply(sum, 2) // trace will record the call
 c.AddToMemory(product) // trace will record the call
 return c.GetMemory() // trace will record the call
}

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

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

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

Tracing Result:

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

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


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

Each event contains:

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

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

Automatic Context Generation:

A context is automatically generated from the trace file:

1

$ archlint trace ./traces -o contexts.yaml

Result - formal context description in YAML:

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


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

The context includes:

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

Visualizations: Sequence Diagram and Graph

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

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

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

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

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

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

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

Key features of the behavioral graph:

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

Behavioral Architecture Coverage Metrics

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

Key metrics:

Component coverage:

1

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

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

Number of contexts:

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

Critical path coverage:

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

Dead code detection:

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

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

Conclusion: Two Views of Architecture

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

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

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

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

What’s Next

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

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

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

Tools

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

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

The project includes:

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

Working with Chaos in Architecture

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

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

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

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

What working with chaotic architectures taught me

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

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

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

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

Every messy system holds a story

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

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