The subject is a production Android app: 100+ Gradle modules, a feature-per-module architecture, two product flavors. Big enough that no human holds it all in their head — which is exactly the condition under which an agent’s ability to navigate without guessing stops being a nicety and becomes the whole game.

The repo has two halves that do two different jobs:

• .claude/ tells the agent how to work here — the conventions, the procedures, the review standards.
• docs/ tells the agent what the system does — the behavior specs, the module maps, the analytics contracts.

Neither is useful without the other. A skill that knows how to implement a feature still has to read a doc to learn what the feature is. Let’s take them in turn.

Half One: .claude/ — How the Agent Works

1
2
3
4
5
6

.claude/
├── rules/      17 topical convention files  (the rubric)
├── skills/     24 named workflows           (the procedures)
├── agents/     10 specialist sub-agents     (the reviewers)
├── hooks/      shell hooks on edit/stop     (the guardrails)
└── scripts/    deterministic helpers        (the non-AI work)

Rules — the team’s conventions as a checklist

.claude/rules/*.md are narrow, single-topic files: mvi-architecture.md, navigation.md, app-result.md, webview.md, analytics.md, and so on. Each one codifies one convention, and the format matters more than you’d expect. They aren’t prose essays — they’re rubrics, with ✅ correct / ❌ wrong pairs the agent can pattern-match against.

Here’s the real app-result.md, which governs how the codebase chains fallible operations:

1
2
3
4
5

// ❌ WRONG: map with an AppResult-returning lambda → AppResult<AppResult<Profile>>
val nested = result.map { user -> fetchUserProfile(user.id) }

// ✅ CORRECT: flatMap flattens the nested result
val profile = result.flatMap { user -> fetchUserProfile(user.id) }

Capability unlocked: the AI writes code that matches your conventions, not the statistical average of GitHub. Without this file, a model produces idiomatic-but-generic Kotlin. With it, the model produces code that looks like the rest of this repo — internal visibility, no public constants, flatMap over manual when. The convention travels with the code, so it’s correct on every run, for every contributor, human or model.

The clever part is the feedback loop: a skill called /review-and-rule watches how the codebase actually handles a pattern, then writes or updates the rule file itself. Conventions discovered in review become rules enforced in the next implementation. The rubric maintains itself.

Skills — procedures, not prompts

A skill is a named, multi-phase workflow invoked with /skill-name. This repo has 24 of them. They’re the difference between asking an agent to “implement a feature” and handing it the team’s actual playbook for doing so.

/implement-feature is representative. It doesn’t just write code — it runs phases:

1. Interview — asks a fixed set of requirement questions via structured prompts.
2. Design — derives the MVI shape (State / Action / Event / Reducer) from the answers.
3. Scaffold — generates the api-* + feature-* module pair.
4. Implement — writes real logic and Compose UI following the rules above.
5. Self-review — invokes the code-reviewer sub-agent before handing back.

Others are sharper tools: /task-worker takes a Jira ticket and runs it end-to-end with up to three auto-repair loops; /check-coverage runs JaCoCo, finds the gaps, and writes tests in batches until a target is met; /discovery-to-srs turns a rough draft into a structured spec and has an independent agent validate it.

Capability unlocked: the AI executes a process instead of improvising one. Improvisation is where agents drift — every run reinvents the approach, and quality is a coin flip. A skill pins the steps while leaving the content to the model. The result is repeatability: /implement-feature produces the same module shape today as it did last month, because the phases are fixed even though the code is new.

Sub-agents — specialists with fresh context and a narrow rubric

.claude/agents/ holds 10 sub-agent definitions, most of them reviewers: pr-review-architecture, pr-review-compose, pr-review-performance, pr-review-tests, pr-review-package-structure, pr-review-code-quality. The /review-pr-advanced skill fans all six out in parallel, each in its own context window, each handed exactly one job.

The architecture reviewer’s prompt is a tight checklist — “Reducers call Use Cases, not Repositories”, “every implementation class must be internal“, “navigation goes through a Router interface” — and it’s explicitly told not to review formatting or Compose perf, because other agents own those.

Capability unlocked: depth without dilution. A single agent asked to “review this PR” spreads its attention thin and its context fills with noise. Six specialists, each with a focused rubric and a clean context, each catch things a generalist misses — and they run concurrently, so the wall-clock cost is one review, not six. This is the find → specialize → verify shape that one big prompt can’t replicate.

Hooks and scripts — the parts that shouldn’t be AI

Two more layers round it out. Hooks (post-edit-review-reminder.sh, pre-stop-review-check.sh) are shell scripts the harness fires on edit and before the agent stops — they nudge the review step so it can’t be silently skipped. Scripts (the JaCoCo XML parsers, the doc-index generators) are plain Python: deterministic work that would be wasteful and unreliable to do with a model.

Capability unlocked: the agent knows what not to think about. Parsing an XML coverage report doesn’t need a language model; enforcing “review before you stop” shouldn’t depend on the model remembering to. Pushing this work into hooks and scripts makes the system both cheaper and more reliable — the AI spends its tokens on judgment, not bookkeeping.

Half Two: docs/ — What the System Does

The product documentation lives in a nested git repository cloned at docs/, with the actual content under docs/docs/. That nesting is deliberate (more on why in the repo below), but the structure inside is the interesting part:

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

docs/docs/
├── INDEX.md          module → feature lookup  (generated)
├── llms.txt          curated manifest for agents
├── STYLE.md          machine-checkable doc conventions
├── GLOSSARY.md       acronyms (WL, LP, SRS, TNB…)
├── features/
│   └── <Feature>/
│       ├── README.md         folder index    (generated)
│       ├── modules.md        module map       (source of truth)
│       ├── <Feature>.srs.md  the primary spec
│       ├── analytics/        event specs
│       ├── _drafts/          WIP  (status: draft)
│       └── _archive/         deprecated
└── technical/        cross-cutting reference

INDEX.md — the lookup table that kills blind search

INDEX.md maps every one of the ~265 code modules to the feature it belongs to:

1
2
3

| `:features:feature-alerts-feed`       | Alerts            |
| `:features:feature-instrument-tab-news` | Instrument screen |
| `:services:service-deep-links`        | Deep links        |

Crucially, the module → feature section is generated from each feature’s modules.md by a Python script — so it can’t drift from reality by hand.

Capability unlocked: the agent’s first move is a lookup, not a search. Drop the model into a 100-module repo with no index and “where does the alerts feed live?” becomes a fan-out of greps and guesses. With INDEX.md, it’s one hop: module → feature folder → spec. Every skill in the repo starts from this same hop. The 45 feature folders mean the difference between an agent that explores and an agent that retrieves.

llms.txt and STYLE.md — a contract for machine readers

llms.txt is the emerging convention for an AI entry point: a curated manifest pointing at each feature’s primary spec, with drafts and archives deliberately excluded so the agent reads the authoritative doc first.

STYLE.md is the part I find most underrated. It’s a style guide that’s actually enforceable: every doc must declare a type from a fixed enum (srs, overview, api, analytics…), every spec must cover the three user states (guest / registered / subscribed), filenames follow a canonical pattern — and a CI gate (check-doc-filenames.py, run-quality-gates.py) fails the build when they don’t.

Capability unlocked: AI-written docs come out uniform. When /discovery-to-srs or the Jira pipeline generates a spec, STYLE.md is the schema it writes against — so machine-authored docs land in the same shape as hand-written ones, and the next agent that reads them knows exactly where to look. A style guide that a human merely reads is advisory; one that’s an enum plus a CI gate is a contract both sides honor.

modules.md and the lifecycle folders — honesty over time

Each feature’s modules.md is the source of truth for which code belongs to it, and the rule is that adding a module in code means updating modules.md in the same PR. The _drafts/ and _archive/ subfolders, gated by a status field, keep work-in-progress and dead docs from polluting what the agent treats as authoritative.

Capability unlocked: the agent can trust what it reads. The single most expensive failure mode for doc-driven AI is confidently acting on a stale spec — it never throws an error, it just does the wrong thing. Same-PR module updates and explicit lifecycle status are the cheap, unglamorous machinery that keeps “the docs say X” and “the code does X” from diverging.

The Connective Tissue

The two halves meet in a single invariant that every skill follows: resolve, read, then act.

1
2
3
4
5
6

Jira ticket  →  INDEX.md (module → feature)
             →  modules.md (which modules)
             →  <Feature>.srs.md (documented behavior)
             →  implement, guided by .claude/rules/*
             →  review via specialist sub-agents
             →  /update-docs flags which specs drifted

task-worker lives this loop end to end. It never guesses where a feature is or how it should behave — it looks both up, builds against the documented contract, implements under the rules, reviews with the specialists, and then checks whether its own changes made the docs stale. The systems from the first post — the Doc-Chat Q&A bot, the Jira→Docs pipeline — are just more consumers of this same structure. They work because the index, the specs, and the rules already exist for them to read.

What the AI Can Do Now — The Short Version

Why In the Repo Specifically

Every benefit above depends on this context living in the repository, not in Confluence or a wiki. Four reasons, all of which compound:

• Auto-loaded. CLAUDE.md and .claude/ are pulled into every agent session with zero setup. A wiki page has to be found, fetched, and pasted — which means it usually isn’t.
• Version-locked. The docs are at the same commit as the code. Check out a branch from six months ago and you get that branch’s specs and rules — no “which version of this Confluence page matches this tag?” guesswork.
• Same diff. A behavior change and its doc update ride the same PR, reviewed together. /update-docs exists precisely to keep that link tight. Confluence updates happen weeks later, if ever.
• Greppable and cache-friendly. Plain text on the live filesystem means an agent can Grep the current state — no embedding index to re-sync (the no-vector-DB argument from the first post). And low-churn plain text keeps the prompt cache warm, which is a real cost line at scale.

Bottom Line

An agent-ready repo isn’t one big clever prompt. It’s two boring, layered halves: a .claude/ that encodes how the team works and a docs/ that encodes what the system does — joined by the discipline of resolve, read, act. Each file is small and unglamorous on its own; together they’re the difference between an AI that explores your codebase and one that operates it.

The investment is real, but it’s the same investment that makes a codebase legible to a new senior engineer — and now you’re making it once for every future agent run as well. Start with the three files from the first post (CLAUDE.md, a few rules, an index), ship one skill, and let /review-and-rule grow the rest from what your reviews already know.

Further Reading

• Documentation in the AI Era: Docs Are the New Source Code — the systems built on top of this structure
• D3: Documentation Driven Development — the process that produces the specs
• Anthropic — Claude Code best practices and Agent Skills
• llms.txt — the machine-readable entry-point convention

Объект — продакшен Android-приложение: 100+ Gradle-модулей, архитектура «модуль на фичу», два продуктовых флейвора. Достаточно большое, чтобы никто не держал его целиком в голове, — а именно в этих условиях способность агента ориентироваться без догадок перестаёт быть приятным бонусом и становится сутью дела.

У репозитория две половины, решающие две разные задачи:

• .claude/ говорит агенту, как здесь работать, — соглашения, процедуры, стандарты ревью.
• docs/ говорит агенту, что делает система, — спецификации поведения, карты модулей, контракты аналитики.

Ни одна не работает без другой. Навык, знающий, как реализовать фичу, всё равно должен прочитать документ, чтобы узнать, что это за фича. Разберём по порядку.

Половина первая: .claude/ — как агент работает

1
2
3
4
5
6

.claude/
├── rules/      17 тематических файлов соглашений  (рубрика)
├── skills/     24 именованных воркфлоу             (процедуры)
├── agents/     10 специализированных суб-агентов   (ревьюеры)
├── hooks/      shell-хуки на edit/stop             (страховка)
└── scripts/    детерминированные помощники         (не-ИИ работа)

Правила — соглашения команды в виде чек-листа

.claude/rules/*.md — узкие однотемные файлы: mvi-architecture.md, navigation.md, app-result.md, webview.md, analytics.md и так далее. Каждый кодифицирует одно соглашение, и формат важнее, чем кажется. Это не эссе — это рубрики с парами ✅ верно / ❌ неверно, с которыми агент сверяется по образцу.

Вот реальный app-result.md, описывающий, как в кодовой базе сцепляются операции, способные упасть:

1
2
3
4
5

// ❌ НЕВЕРНО: map с лямбдой, возвращающей AppResult → AppResult<AppResult<Profile>>
val nested = result.map { user -> fetchUserProfile(user.id) }

// ✅ ВЕРНО: flatMap «разворачивает» вложенный результат
val profile = result.flatMap { user -> fetchUserProfile(user.id) }

Раскрытая способность: ИИ пишет код по вашим соглашениям, а не по статистическому среднему GitHub. Без этого файла модель выдаёт идиоматичный, но обобщённый Kotlin. С ним — код, похожий на остальной этот репозиторий: internal-видимость, никаких публичных констант, flatMap вместо ручного when. Соглашение едет вместе с кодом, поэтому оно соблюдается при каждом запуске, для каждого участника — человека или модели.

Самое изящное — обратная связь: навык /review-and-rule наблюдает, как кодовая база на самом деле обрабатывает паттерн, и сам пишет или обновляет файл правила. Соглашения, найденные на ревью, становятся правилами, применяемыми при следующей реализации. Рубрика поддерживает себя сама.

Навыки — процедуры, а не промпты

Навык — это именованный многофазный воркфлоу, вызываемый через /skill-name. В этом репозитории их 24. Это и есть разница между «попросить агента реализовать фичу» и «вручить ему реальный регламент команды».

/implement-feature — показательный пример. Он не просто пишет код, а проходит фазы:

1. Интервью — задаёт фиксированный набор вопросов о требованиях через структурированные запросы.
2. Дизайн — выводит из ответов MVI-форму (State / Action / Event / Reducer).
3. Каркас — генерирует пару модулей api-* + feature-*.
4. Реализация — пишет реальную логику и Compose UI по правилам выше.
5. Саморевью — вызывает суб-агента code-reviewer перед возвратом результата.

Другие навыки острее: /task-worker берёт Jira-тикет и проводит его от начала до конца с тремя циклами авто-починки; /check-coverage запускает JaCoCo, находит пробелы и пишет тесты пачками, пока не достигнет цели; /discovery-to-srs превращает черновик в структурированную спецификацию и отдаёт независимому агенту на валидацию.

Раскрытая способность: ИИ выполняет процесс, а не импровизирует его. Импровизация — это там, где агенты «уплывают»: каждый запуск заново изобретает подход, и качество — подбрасывание монетки. Навык фиксирует шаги, оставляя содержание модели. Результат — воспроизводимость: /implement-feature сегодня выдаёт ту же форму модуля, что и месяц назад, потому что фазы фиксированы, хотя код новый.

Суб-агенты — специалисты со свежим контекстом и узкой рубрикой

В .claude/agents/ — 10 определений суб-агентов, большинство из них ревьюеры: pr-review-architecture, pr-review-compose, pr-review-performance, pr-review-tests, pr-review-package-structure, pr-review-code-quality. Навык /review-pr-advanced запускает все шесть параллельно, каждого в своём контекстном окне, с одной-единственной задачей.

Промпт архитектурного ревьюера — плотный чек-лист: «Reducer вызывает Use Case, а не Repository», «каждый класс реализации должен быть internal», «навигация идёт через интерфейс Router», — и ему явно сказано не проверять форматирование или производительность Compose, потому что за это отвечают другие агенты.

Раскрытая способность: глубина без размывания. Один агент, которого просят «отревьюить этот PR», распыляет внимание, а его контекст забивается шумом. Шесть специалистов, каждый с фокусной рубрикой и чистым контекстом, ловят то, что упускает универсал, — и работают одновременно, так что по времени это одно ревью, а не шесть. Это форма найти → специализировать → проверить, которую один большой промпт не повторит.

Хуки и скрипты — то, что не должно быть ИИ

Ещё два слоя замыкают картину. Хуки (post-edit-review-reminder.sh, pre-stop-review-check.sh) — это shell-скрипты, которые харнесс запускает при редактировании и перед остановкой агента; они подталкивают к шагу ревью, чтобы его нельзя было молча пропустить. Скрипты (парсеры XML-отчётов JaCoCo, генераторы индексов документации) — обычный Python: детерминированная работа, которую расточительно и ненадёжно делать моделью.

Раскрытая способность: агент знает, о чём не надо думать. Разбор XML-отчёта о покрытии не требует языковой модели; соблюдение правила «ревью перед остановкой» не должно зависеть от того, вспомнит ли о нём модель. Вынос этой работы в хуки и скрипты делает систему дешевле и надёжнее — ИИ тратит токены на суждения, а не на бухгалтерию.

Половина вторая: docs/ — что делает система

Продуктовая документация живёт во вложенном git-репозитории, склонированном в docs/, а само содержимое — в docs/docs/. Вложенность сделана осознанно (про почему именно в репозитории — ниже), но интересна как раз структура внутри:

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

docs/docs/
├── INDEX.md          модуль → фича  (генерируется)
├── llms.txt          выверенный манифест для агентов
├── STYLE.md          машинно-проверяемые соглашения
├── GLOSSARY.md       акронимы (WL, LP, SRS, TNB…)
├── features/
│   └── <Feature>/
│       ├── README.md         индекс папки    (генерируется)
│       ├── modules.md        карта модулей    (источник истины)
│       ├── <Feature>.srs.md  основная спека
│       ├── analytics/        спеки событий
│       ├── _drafts/          в работе  (status: draft)
│       └── _archive/         устаревшее
└── technical/        сквозной справочник

INDEX.md — таблица соответствий, убивающая слепой поиск

INDEX.md сопоставляет каждый из ~265 модулей кода с фичей, к которой он относится:

1
2
3

| `:features:feature-alerts-feed`         | Alerts            |
| `:features:feature-instrument-tab-news` | Instrument screen |
| `:services:service-deep-links`          | Deep links        |

Важно: секция «модуль → фича» генерируется из modules.md каждой фичи Python-скриптом — поэтому она не может разойтись с реальностью из-за ручной правки.

Раскрытая способность: первый ход агента — это поиск по индексу, а не перебор. Бросьте модель в репозиторий из 100 модулей без индекса, и «где живёт лента алертов?» превращается в веер grep’ов и догадок. С INDEX.md — это один прыжок: модуль → папка фичи → спека. Каждый навык в репозитории начинается с этого же прыжка. 45 папок фич — это разница между агентом, который исследует, и агентом, который извлекает.

llms.txt и STYLE.md — контракт для машинных читателей

llms.txt — это формирующееся соглашение о точке входа для ИИ: выверенный манифест, указывающий на основную спеку каждой фичи, причём черновики и архив намеренно исключены, чтобы агент сначала читал авторитетный документ.

STYLE.md — на мой взгляд, самое недооценённое. Это гайд по стилю, который реально проверяем: каждый документ обязан объявить type из фиксированного перечня (srs, overview, api, analytics…), каждая спека обязана покрывать три состояния пользователя (гость / зарегистрированный / с подпиской), имена файлов следуют канону — и CI-гейт (check-doc-filenames.py, run-quality-gates.py) роняет сборку, когда это не так.

Раскрытая способность: документы, написанные ИИ, выходят однородными. Когда /discovery-to-srs или Jira-пайплайн генерирует спеку, STYLE.md — это схема, под которую она пишется; так машинно-созданные документы получаются той же формы, что и написанные вручную, и следующий агент, читающий их, точно знает, куда смотреть. Гайд, который человек просто читает, — рекомендательный; гайд, который есть перечень плюс CI-гейт, — контракт, соблюдаемый обеими сторонами.

modules.md и папки жизненного цикла — честность во времени

modules.md каждой фичи — это источник истины о том, какой код к ней относится, и правило такое: добавил модуль в коде — обнови modules.md в том же PR. Подпапки _drafts/ и _archive/, управляемые полем status, не дают работе-в-процессе и мёртвым документам засорять то, что агент считает авторитетным.

Раскрытая способность: агент может доверять тому, что читает. Самый дорогой режим отказа для документ-ориентированного ИИ — уверенно действовать по устаревшей спеке: ошибки не будет, он просто сделает не то. Обновления модулей в том же PR и явный статус жизненного цикла — это дешёвый, невзрачный механизм, не дающий «в документации написано X» и «код делает X» разойтись.

Соединительная ткань

Две половины встречаются в одном инварианте, которому следует каждый навык: разрешить, прочитать, действовать.

1
2
3
4
5
6

Jira-тикет  →  INDEX.md (модуль → фича)
            →  modules.md (какие модули)
            →  <Feature>.srs.md (задокументированное поведение)
            →  реализация под управлением .claude/rules/*
            →  ревью через специализированных суб-агентов
            →  /update-docs помечает, какие спеки устарели

task-worker проживает этот цикл от и до. Он никогда не гадает, где фича и как она должна себя вести, — он ищет и то и другое, строит против задокументированного контракта, реализует под правилами, ревьюит со специалистами, а затем проверяет, не сделали ли его же изменения документацию устаревшей. Системы из первого поста — Q&A-бот Doc-Chat, пайплайн Jira→Docs — это просто ещё потребители той же структуры. Они работают, потому что индекс, спеки и правила уже существуют, чтобы их читать.

Что теперь умеет ИИ — коротко

Почему именно в репозитории

Каждая выгода выше зависит от того, что этот контекст живёт в репозитории, а не в Confluence или вики. Четыре причины, и все они усиливают друг друга:

• Автозагрузка. CLAUDE.md и .claude/ подтягиваются в каждую сессию агента без всякой настройки. Вики-страницу нужно найти, скачать и вставить — а значит, обычно её не вставляют.
• Привязка к версии. Документация на том же коммите, что и код. Переключитесь на ветку полугодовой давности — получите спеки и правила именно той ветки, без гаданий «какая версия этой Confluence-страницы соответствует этому тегу?».
• Тот же diff. Изменение поведения и обновление его документа едут в одном PR и ревьюятся вместе. /update-docs существует именно чтобы держать эту связь тугой. Confluence обновляют неделями позже, если вообще.
• Грепается и дружит с кэшем. Простой текст на живой файловой системе означает, что агент может Grep по текущему состоянию — без индекса эмбеддингов, который надо пересинхронизировать (аргумент «без векторной БД» из первого поста). А малоизменчивый простой текст держит промпт-кэш тёплым, что на масштабе — реальная статья расходов.

Итог

Репозиторий, готовый для агента, — это не один большой умный промпт. Это две скучные слоистые половины: .claude/, кодирующая, как работает команда, и docs/, кодирующая, что делает система, — соединённые дисциплиной разрешить, прочитать, действовать. Каждый файл сам по себе мал и невзрачен; вместе они — разница между ИИ, который исследует вашу кодовую базу, и ИИ, который ею управляет.

Вложение реальное, но это то же вложение, что делает кодовую базу понятной новому senior-инженеру, — только теперь вы делаете его один раз и сразу на все будущие запуски агента. Начните с трёх файлов из первого поста (CLAUDE.md, несколько правил, индекс), выпустите один навык и дайте /review-and-rule вырастить остальное из того, что ваши ревью уже знают.

Что почитать дальше

• Документация в эпоху ИИ: документация — новый исходный код — системы, построенные поверх этой структуры
• D3: Разработка, управляемая документацией — процесс, производящий спеки
• Anthropic — Claude Code best practices и Agent Skills
• llms.txt — соглашение о машинно-читаемой точке входа

Именно на этом допущении команды всегда и спотыкались. Поэтому здесь я максимально приближаю объектив к одному конкретному ответу на вопрос «а как надёжно произвести эту спецификацию?» — к одному переиспользуемому скилу, который берёт черновой документ-исследование и превращает его в аккуратный SRS, опирающийся на код, а затем поручает второму агенту проверить результат, прежде чем вы на него положитесь.

Сначала — что такое скил?

Скил (skill) — это именованная переиспользуемая процедура, которую агент может вызвать: папка с файлом-инструкцией SKILL.md (и, опционально, со вспомогательными агентами, скриптами или шаблонами), в которой закодировано, как хорошо выполнять повторяющуюся задачу. Вместо того чтобы каждый раз заново объяснять один и тот же многошаговый процесс в новом промпте, вы записываете его один раз — и агент ему следует: те же шаги, та же планка качества, тот же формат вывода при каждом запуске.

Это разница между «иди напиши спецификацию», сказанным новичку, и чек-листом, который старший инженер отшлифовал на десятке фич. Скил — это и есть такой чек-лист, ставший исполняемым.

Проблема: разрыв между черновиком и спецификацией

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

• Остаётся расплывчатой. В черновике написано «показать пользователю его элементы». Не написано, что видит разлогиненный пользователь, что показывается, пока список грузится, что — когда список пуст, и что происходит при ошибке запроса. Именно в этих пробелах и рождаются баги.
• Не опирается на код. Спецификация, написанная только по черновику, выдумывает имена модулей, угадывает форму API и игнорирует паттерны, которые уже есть в репозитории. Потом разработчик тратит первый день на сверку спецификации с реальностью.
• Расползается формат. Каждый пишет спецификации немного по-своему, поэтому никакие два документа не читаются одинаково — а LLM, которая прочитает их позже (см. два предыдущих поста), получает разнородный корпус.
• Никто её не проверяет. Спецификации верят потому, что она существует, а не потому, что её сверили. Ошибки доживают до самого кода.

Это и есть та дорогая, скучная работа, дешевизна которой — обязательное условие для D3. Скил — это способ сделать её дешёвой и надёжной: не за счёт того, что пишешь быстрее, а за счёт того, что вся дисциплина закодирована один раз.

Анатомия скила

Скил — это папка из двух частей: SKILL.md, задающий рабочий процесс, и вспомогательный агент-рецензент, которого он запускает ближе к концу. Вот метаданные-триггер в начале SKILL.md:

1
2
3
4
5
6
7
8

---
name: discovery-to-srs
description: Превращает черновой/исследовательский Markdown-документ в
  аккуратную спецификацию (SRS). Срабатывает на «напиши SRS»,
  «преврати это исследование в документацию», «задокументируй фичу»
  или когда пользователь делится черновиком с описанием фичи.
argument-hint: "<путь-к-discovery.md>"
---

description — не украшение, а то, как агент решает, когда взяться за этот скил. Формулировка вокруг реальных слов пользователя («у меня есть черновик», «задокументируй фичу») и делает вызов автоматическим, а не тем, что надо помнить самому.

Тело SKILL.md — это рабочий процесс из восьми шагов. По отдельности шаги важны меньше, чем форма, которую они образуют, поэтому вот он целиком:

1
2
3
4
5
6
7
8
9
10

1. Прочитать черновик       → извлечь скоуп, экраны, модули, что расплывчато
2. Исследовать и закрыть    → искать в коде и докуменах ПАРАЛЛЕЛЬНО
   пробелы
3. Задать уточняющие        → только то, что нельзя достать из кода/докум.
   вопросы
4. Определить расположение   → новая фича или существующая папка
5. Написать SRS              → следовать каноническому формату
6. Запустить независимого рецензента
7. Применить замечания       → доработать, при необходимости пере-проверить
8. Показать результат        → НЕ начинать реализацию

Четыре из этих шагов — там, где сосредоточена настоящая выгода.

Шаг 2 — закрыть пробелы по реальному коду

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

• В документации: прочитать индекс, чтобы понять, что уже есть и как оно организовано; если у фичи уже есть папка — прочитать её спецификацию и сквозные технические заметки (навигация, авторизация, диплинки).
• В коде: найти grep’ом модули, относящиеся к фиче; прочитать соответствующие файлы состояния/логики, чтобы узнать реально реализованное поведение; свериться с графами навигации, где находятся экраны; прочитать интерфейсы API и модели данных; проверить флаги, управляющие раскаткой.

Главная инструкция здесь вот какая: если поведение выведено из кода, а не заявлено в черновике, его всё равно правильно включить — вы же его проверили. Именно это правило превращает расплывчатый черновик в спецификацию, опирающуюся на то, что система делает на самом деле.

Шаг 3 — спрашивать только то, что нельзя вывести

После исследования агент определяет, что всё ещё неясно, и спрашивает — но скил прямо требует, чтобы это был крайний случай, чтобы вопросы шли пачкой и только по настоящим неизвестным: неоднозначный скоуп, противоречия между черновиком и кодом, неописанное состояние пользователя («что должен видеть гость?») или интерфейс, у которого нигде нет дизайн-референса. Нельзя спрашивать о том, что можно выяснить самому из кода или документации. В этом и разница между ассистентом, который уважает ваше время, и тем, кто превращает любую задачу в допрос.

Шаг 5 — закрепить формат за каноническим примером

Скил не описывает формат вывода абстрактно — он указывает на реальную, уже существующую спецификацию как на эталон стиля и перечисляет обязательные разделы: обзор, таблицу «модуль → назначение», функциональные требования по каждому экрану с разбивкой по состояниям пользователя (гость, бесплатный, платный…), интеграцию с API и флаги. Правила стиля конкретны: повелительные формулировки («Нажатие на X открывает Y»), явная персистентность («хранится локально» против «только в рантайме»), точные имена модулей в обратных кавычках. Привязка к примеру и держит все спецификации скила одинаково читаемыми — что как раз и делает итоговый корпус понятным для следующего агента.

Шаги 6–7 — независимый рецензент со своим чек-листом

Эту часть чаще всего пропускают самодельные промпты — а она важнее всего. Когда SRS написан, скил запускает отдельного агента-рецензента со свежим контекстом и собственными инструкциями. Это не расплывчатое «глянь-ка» — у рецензента настоящий чек-лист:

• Полнота — покрыт ли каждый экран? Каждое состояние пользователя? Состояния загрузки, пустоты и ошибки? Каждый интерактивный элемент? Каждый флаг?
• Точность — действительно ли существуют в кодовой базе указанные имена модулей, эндпоинты API и имена флагов? Имя, которое никуда не ведёт, — это критическая проблема, а не придирка.
• Согласованность — не противоречит ли это какой-нибудь уже задокументированной фиче?
• Формат и открытые вопросы — соблюдена ли принятая структура и что разработчику всё ещё придётся спросить перед сборкой?

Рецензент завершает одним из трёх вердиктов — APPROVED, APPROVED WITH NOTES или NEEDS REVISION — и процесс ветвится по нему: одобрить и закончить, применить замечания и закончить либо доработать и запустить рецензента снова. Его финальную инструкцию стоит процитировать: «Будь прямым. Не раздувай находки ради видимости тщательности и не смягчай критические проблемы ради вежливости. Цель — пригодный документ, а не идеальная оценка».

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

Почему скил, а не просто хороший промпт

Всё это можно один раз вставить в чат и получить приличный SRS. Причина сделать из этого скил — во всём, что происходит во второй раз:

• Согласованность. Каждая спецификация выходит в одной и той же форме, поэтому корпус остаётся читаемым — и для людей, и для агентов, которые прочитают его позже.
• Планка качества путешествует. Правило закрытия пробелов, правило «не спрашивай то, что можно вывести», чек-лист рецензента — это выстраданные уроки. Скил фиксирует их один раз, чтобы они применялись при каждом запуске, а не жили в чьей-то голове.
• Это контрольная точка, а не чёрный ящик. Процесс намеренно заканчивается до реализации: SRS — это и есть результат, проверенный и согласованный, ровно тот артефакт, который D3 хочет зафиксировать до старта кода.
• Он компонуется. Этот скил производит спецификацию; другие скилы (спланировать фичу, реализовать её, отревьюить PR) её потребляют. Весь конвейер D3 — это скилы, передающие друг другу типизированные артефакты.

Промпт — это разовая вещь. Скил — это процесс, которому можно доверить отработать одинаково и в пятницу в 17:00, и в тот первый раз, когда вы его записали.

Об инструментах

Я описываю это на примере Claude и его формата скилов, потому что на нём это и работает, но сама идея переносима. Скил — это всего лишь записанная процедура плюс опциональный агент-рецензент; любая агентская среда, которая умеет читать файлы, искать по кодовой базе и запускать второй проход, способна сделать то же самое. Выгода не в вендоре, а в трёх вещах, которые доступны любой способной модели: рабочий процесс, достаточно конкретный, чтобы следовать ему по шагам; дисциплина сверять с реальным кодом, а не угадывать; и независимый рецензент, чтобы ничего не уехало непроверенным.

Итог

D3 говорит: пиши спецификацию до кода. «Документация — новый исходный код» говорит: эту спецификацию и будет читать каждый последующий агент. Этот скил — маленькая конкретная машина, которая делает производство такой спецификации дешёвым и заслуживающим доверия: прочитать черновик, закрыть его пробелы по реальному коду, спросить только то, что нельзя вывести, написать в единой форме и дать второму агенту разобрать её по косточкам, прежде чем на неё кто-то положится. Закодируйте эту дисциплину один раз — и сырой черновик станет проверенным справочником. Каждый раз, а не только когда кто-то вспомнит, что надо быть внимательным.

That assumption is exactly where teams have always failed. So this post zooms all the way in on a single, concrete answer to “but how do you reliably produce that spec?” — one reusable skill that takes a rough discovery document and turns it into a polished, code-grounded SRS, then has a second agent review it before you trust the result.

First, what is a skill?

A skill is a named, reusable procedure an agent can invoke — a folder containing a SKILL.md instruction file (and optionally helper agents, scripts, or templates) that encodes how to do a recurring job well. Instead of re-explaining the same multi-step process in a fresh prompt every time, you write it down once and the agent follows it: same steps, same quality bar, same output format, every run.

Think of it as the difference between telling a new hire “go write a spec” and handing them a checklist that a senior engineer refined over a dozen features. The skill is that checklist, made executable.

The Problem: the discovery-to-spec gap

Every feature starts as something rough — bullet points in a doc, a screenshot, a paragraph from product, a few notes from a discovery call. Turning that into a specification a developer can build from is real work, and it fails in four predictable ways:

• It stays vague. The draft says “show the user their items.” It doesn’t say what a logged-out user sees, what shows while the list loads, what shows when the list is empty, or what happens when the API call fails. Those gaps are exactly where bugs are born.
• It isn’t grounded in the code. A spec written from the draft alone invents module names, guesses at API shapes, and ignores patterns that already exist in the repo. The developer then spends the first day reconciling the spec with reality.
• The format drifts. Everyone writes specs a little differently, so no two documents are navigable the same way — and an LLM reading them later (see the previous two posts) gets an inconsistent corpus.
• Nobody checks it. The spec is trusted because it exists, not because it was verified. Mistakes survive all the way into code.

This is the expensive, boring work D3 depends on being cheap. A skill is how you make it cheap and reliable — not by writing faster, but by encoding the whole discipline once.

Anatomy of the skill

The skill is a folder with two parts: a SKILL.md that defines the workflow, and a helper reviewer agent it spawns near the end. Here’s the trigger metadata at the top of SKILL.md:

1
2
3
4
5
6
7
8

---
name: discovery-to-srs
description: Converts a Markdown discovery/draft document into a polished
  Software Requirements Specification (SRS). Triggers on "write an SRS",
  "turn this discovery into docs", "document this feature", or when the
  user shares a draft describing a feature they want documented.
argument-hint: "<path-to-discovery.md>"
---

The description isn’t decoration — it’s how the agent decides when to reach for this skill. Phrasing it around the user’s actual words (“I have a draft”, “document this feature”) is what makes invocation feel automatic rather than something you have to remember.

The body of SKILL.md is an eight-step workflow. The steps matter less individually than the shape they form, so here it is end to end:

1
2
3
4
5
6
7
8

1. Read the discovery doc      → extract scope, screens, modules, what's vague
2. Research & fill the gaps    → search code + docs IN PARALLEL
3. Ask clarifying questions    → only what code/docs can't answer
4. Determine the location      → new vs. existing feature folder
5. Write the SRS               → follow a canonical format
6. Spawn an independent reviewer
7. Apply review feedback       → revise, re-review if needed
8. Present the result          → do NOT start implementation

Four of those steps are where the real leverage lives.

Step 2 — Fill the gaps from the actual code

This is the step that separates a real spec from a polished-looking guess. Rather than expanding the draft on its own terms, the agent explores the code and the docs in parallel to fill in everything the draft left vague:

• In the docs: read the docs index to learn what already exists and how it’s organized; if the feature already has a folder, read its existing spec and any cross-cutting technical notes (navigation, auth, deep links).
• In the code: grep for modules related to the feature; read the relevant state/logic files to learn the actually implemented behavior; check navigation graphs for where screens fit; read API interfaces and data models; check any feature flags gating rollout.

The instruction the skill gives here is the important one: if a behavior is inferred from code rather than stated in the draft, it’s still correct to include — you just verified it. That single rule is what turns a vague draft into a spec grounded in what the system actually does.

Step 3 — Ask only what you can’t infer

After research, the agent identifies what’s still unclear and asks — but the skill is explicit that this is a last resort, batched, and limited to genuine unknowns: ambiguous scope, conflicting signals between draft and code, an undescribed user state (“what should a guest see?”), or UI with no design reference anywhere. It must not ask about anything it could answer itself from code or docs. This is the difference between an assistant that respects your time and one that turns every task into an interview.

Step 5 — Anchor the format to a canonical example

The skill doesn’t describe the output format in the abstract; it points at a real, existing spec as the style reference and lists the required sections — overview, module-to-purpose table, per-screen functional requirements broken down by user state (guest, free, paid…), API integration, and feature flags. The style rules are concrete: imperative phrasing (“Tapping X opens Y”), explicit persistence (“stored locally” vs. “runtime only”), exact module names in backticks. Anchoring to an example is what keeps every spec the skill produces navigable the same way — which is precisely what makes the resulting corpus readable by the next agent.

Steps 6–7 — An independent reviewer, with its own rubric

This is the part most home-grown prompts skip, and it’s the most important. Once the SRS is written, the skill spawns a separate reviewer agent with a fresh context and its own instructions. It isn’t a vague “check this over” — the reviewer has a real rubric:

• Completeness — is every screen covered? Every user state? Loading, empty, and error states? Every interactive element? Every flag?
• Accuracy — do the module names, API endpoints, and flag names actually exist in the codebase? A name that doesn’t resolve is a critical issue, not a nit.
• Consistency — does it contradict any already-documented feature?
• Format & open questions — does it follow the house structure, and what would a developer still need to ask before building?

The reviewer ends with one of three verdicts — APPROVED, APPROVED WITH NOTES, or NEEDS REVISION — and the workflow branches on it: approve and finish, apply notes and finish, or revise and run the reviewer again. Its closing instruction is worth quoting: “Be direct. Don’t inflate findings to seem thorough, and don’t soften critical issues to seem nice. The goal is a usable document, not a perfect score.”

Two agents, two contexts, two jobs: one writes with full knowledge of the draft and code, the other audits with fresh eyes against a checklist. That separation is what catches the writer’s blind spots — the same reason we don’t let people merge their own PRs unreviewed.

Why a skill, and not just a good prompt

You could paste all of this into a chat once and get a decent SRS. The reason to make it a skill is everything that happens the second time:

• Consistency. Every spec comes out in the same shape, so the corpus stays navigable — for humans and for the agents that read it later.
• The quality bar travels. The gap-filling rule, the “don’t ask what you can infer” rule, the reviewer’s rubric — those are hard-won lessons. A skill captures them once so they apply on every run instead of living in one person’s head.
• It’s a checkpoint, not a black box. The workflow deliberately ends before implementation: the SRS is the deliverable, reviewed and signed off, exactly the artifact D3 wants locked before code begins.
• It composes. This skill produces the spec; other skills (plan a feature, implement it, review the PR) consume it. The whole D3 pipeline is skills handing typed artifacts to one another.

A prompt is a one-off. A skill is a process you can trust to run the same way at 5pm on a Friday as it did the first time you wrote it down.

A note on tooling

I describe this with Claude and its skills format because that’s what it runs on, but the idea is portable. A skill is just a written-down procedure plus an optional reviewer agent — any agent runtime that can read files, search a codebase, and spawn a second pass can do the same thing. The leverage isn’t in the vendor; it’s in three things any capable model can use: a workflow specific enough to follow step by step, the discipline to verify against real code instead of guessing, and an independent reviewer so nothing ships unchecked.

Bottom Line

D3 says write the spec before the code. Docs-as-source-code says that spec is what every later agent will read. This skill is the small, concrete machine that makes producing that spec cheap and trustworthy: read the draft, fill its gaps from the real code, ask only what you can’t infer, write it in a consistent shape, and have a second agent tear it apart before anyone relies on it. Encode that discipline once, and a rough draft becomes a reviewed reference — every time, not just when someone remembers to be careful.

1. Проверка использования диска

Сначала проверьте, какая файловая система переполнена:

1

df -h

Если подозреваете, что закончились inodes (много мелких файлов):

1

df -i

2. Поиск самых больших директорий

Определите, какие папки занимают больше всего места:

1

sudo du -h -d 1 -x / 2>/dev/null | sort -hr | head -20

• -x — сканирует только основную файловую систему.
• Для интерактивного просмотра используйте ncdu:

1
2

sudo apt install ncdu
sudo ncdu -x /

3. Удаление ненужных больших файлов

Ищите необычно большие файлы, особенно в /usr/local, /var или /home. Часто это статические библиотеки (.a) или старые артефакты сборки. Если нашли ненужное — удаляйте:

1
2

sudo rm /путь/к/большому/файлу
sudo ldconfig

4. Исправление «фантомного» использования диска

Если df показывает больше занятого места, чем du, возможно, есть удалённые, но всё ещё открытые процессами файлы. Найдите их так:

1

sudo lsof +L1 2>/dev/null | awk 'NR==1 || $7+0 > 10000000'

Перезапустите процесс, который держит файл (например, Docker):

1

sudo systemctl restart docker

5. Профилактика (ротация логов Docker)

Логи Docker могут незаметно заполнить диск. Настройте ротацию логов в /etc/docker/daemon.json:

1
2
3
4
5
6
7

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "50m",
    "max-file": "3"
  }
}

Перезапустите Docker:

1

sudo systemctl restart docker

Пересоздайте контейнеры, чтобы применить новую политику.

Быстрые команды для очистки

1
2
3
4
5
6
7
8

docker system df
docker container prune -f
docker builder prune -af
docker image prune -af
journalctl --disk-usage
sudo journalctl --vacuum-size=200M
sudo apt autoremove --purge
sudo apt clean

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

1. Check Disk Usage

Start by seeing which filesystem is full:

1

df -h

If you suspect inode exhaustion (lots of tiny files), check:

1

df -i

2. Find Large Directories

Identify which folders use the most space:

1

sudo du -h -d 1 -x / 2>/dev/null | sort -hr | head -20

• -x keeps the scan on the main filesystem.
• For an interactive view, try ncdu:

1
2

sudo apt install ncdu
sudo ncdu -x /

3. Remove Unneeded Large Files

Look for unusually large files, especially in /usr/local, /var, or /home. Static libraries (.a files) and old build artifacts are common culprits. If you find something you no longer need, remove it:

1
2

sudo rm /path/to/large/file
sudo ldconfig

4. Fix “Phantom” Disk Usage

If df shows more used space than du, you may have deleted files still held open by running processes. Find them with:

1

sudo lsof +L1 2>/dev/null | awk 'NR==1 || $7+0 > 10000000'

Restart the process holding the file (e.g., Docker):

1

sudo systemctl restart docker

5. Prevent Future Issues (Docker Log Rotation)

Docker logs can silently fill your disk. Set up log rotation in /etc/docker/daemon.json:

1
2
3
4
5
6
7

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "50m",
    "max-file": "3"
  }
}

Restart Docker:

1

sudo systemctl restart docker

Recreate containers to apply the new policy.

Quick Cleanup Commands

1
2
3
4
5
6
7
8

docker system df
docker container prune -f
docker builder prune -af
docker image prune -af
journalctl --disk-usage
sudo journalctl --vacuum-size=200M
sudo apt autoremove --purge
sudo apt clean

Total recovered: ~7GB. Total time: about 20 minutes. Lesson value: priceless.

“If a feature is not documented, it doesn’t exist. If a feature is documented incorrectly, then it’s broken.”

Most teams write specs the way they write tests for legacy code: after the fact, to make a tool happy. The real design decisions happen in Slack threads, in a Figma comment, in someone’s head during a stand-up. By the time anything is written down, the code already exists and the document is just a description of what was built — not a plan for what to build.

“Spec before code” is not a new idea. README-Driven Development (RDD — coined by Tom Preston-Werner in 2010) and documentation-first workflows have been around for well over a decade, and they always ran into the same wall: writing a complete, accurate spec by hand is expensive and boring, so teams skipped it. The discipline was right; the economics were wrong.

What changed is that an LLM agent will now do most of that expensive work — read the codebase, find the gaps, interview the team, draft the spec, and then build from it. Documentation Driven Development (D3) is that old discipline made cheap: the team produces a complete specification before writing code, with AI woven into every phase — not just the coding at the end. This post walks through the full flow on a feature we actually shipped this way.

If you’ve read my earlier post on Documentation in the AI Era, think of D3 as the process counterpart to that idea: if docs are the new source code, then D3 is the development lifecycle built around them.

The Problem We’re Solving

You already know the symptoms: specs scattered across Slack, Figma, and people’s memory; QA pulled in only after the code is written; AI reached for during coding but never during planning. I won’t belabor them.

The one point worth keeping is the economics. A wrong assumption caught in a spec costs a sentence; caught in code review it costs a branch; caught in production it costs an incident. The fix gets dramatically more expensive the longer the misunderstanding survives — so the highest-leverage move is to push the hard thinking as early as possible. The reason teams didn’t was that early, thorough specs used to be too costly to produce. D3’s bet is that AI has changed that math.

What is D3?

D3 is a process where the team builds a complete specification of a feature before writing code. What that buys each side:

The key shift is that the specification is not paperwork produced alongside the work — it is the work, until the moment code generation begins.

The End-to-End Flow

Every arrow below is a checkpoint, and feedback can loop back at any stage.

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

Product (idea → PRD → prototype)
        │
        ▼
Collecting Requirements  ←──────── Feedback
  [Analyst/Technical Project Manager + Other Teams]
        │
        ▼
Draft SRS ── Review (all stakeholders + QA)
        │
        ▼
Final SRS (approved)  ───→  QA → Test Plan
        │                   (dev can start in parallel)
        ▼
AI-generated implementation specs (SRS × 3)
  UI SRS · Server SRS · Client SRS
  [AI plan ↔ AI review → Dev review]
        │
        ▼
AI Code ↔ AI Review → Dev Review
        │
        ▼
QA / VQA → PROD → Feedback

Let’s walk through the phases.

Phase 1 — Idea & Initiation

Owner: Product. This phase is unchanged from how most teams already work. Product takes a business need, user request, or strategic goal and turns it into an idea → PRD → prototype. A lightweight PRD and/or prototype is enough; it feeds directly into requirements collection. What changes in D3 is everything that comes after this phase.

Phase 2 — Collecting Requirements

Owner: Analyst/Technical Project Manager. Time: ~20 minutes, AI-assisted.

This is where AI first earns its keep. The process is three steps:

1. Consolidate sources into one .md file — PRD, designs, existing docs, API contracts.
2. Claude finds the gaps — it checks the docs against the existing codebase, surfaces unknowns, and lists open questions.
3. Claude interviews the team — it asks targeted questions to fill those gaps, then produces a clean draft.

The important detail: Claude is not guessing from the PRD alone. With code/docs exploration and the Figma MCP, it reads the actual codebase to validate requirements against what is already implemented. It knows which modules exist, which patterns to reuse, and where the new feature plugs in.

In the screenshot above the requirements collector found four open questions from codebase exploration, and rather than inventing answers it asks the team — for example, whether the new drawer should reuse the existing analytics events or define custom ones.

Phase 3 — Review & Final SRS Sign-off

Owner: Analyst/Technical Project Manager + QA + stakeholders.

The draft SRS from Phase 2 is reviewed collectively until everyone signs off. The output is a single Final SRS — one source of truth, approved by all stakeholders. The moment it’s approved, two things happen at once:

• QA writes the test plan straight from the Final SRS. Testing is designed before implementation begins, so bugs are caught in the spec, not in the code.
• Development can start in parallel. The Final SRS is enough to begin; the detailed per-domain specs (next phase) don’t block the kickoff.

A good Final SRS contains:

• Feature requirements and acceptance criteria
• Edge cases and error handling
• API contracts and data flows
• Fallback chains and dependencies

What the Final SRS Looks Like

Abstract process descriptions are easy to nod along to, so here is a concrete one (sanitized into a generic feature). Say we’re adding a partner drawer behind a promo banner.

In module feature-promo-banners, implement a drawer with a list of partners from the API. Reuse the drawer implementation from feature-item-details. The drawer opens only via deep link.

Fallback chain:

1. Primary: Run the promo action (the main partner flow)
2. Fallback 1: Open the Quick Access Drawer
3. Fallback 2: Navigate to the “All Partners” screen

Acceptance criteria:

• If the primary promo API fails (hardcoded config used), keep showing the skeleton and call the Drawer API.
• If the Drawer API succeeds → show the banner; tapping it opens the Quick Access Drawer.
• If the Drawer API also fails → show the banner; tapping it navigates to /partners.

This is the level of detail the team agrees on before the LLM generates any implementation spec or code. There is no ambiguity left for the developer — or the model — to guess at.

Phase 4 — AI-Generated Implementation Specs (SRS × 3)

Owner: Developer + Claude.

The Final SRS says what to build; it doesn’t yet spell out how. That’s the next step, and it’s where the LLM takes over. With a plan-feature skill — plus code/docs exploration and the Figma MCP — Claude expands the Final SRS into three detailed, domain-specific implementation specs:

These are far more detailed than the Final SRS: they reference real files and modules, follow existing codebase patterns, and include concrete implementation examples rather than describing the feature in a vacuum. In practice the agent reads the Final SRS, spawns sub-agents to dig through the codebase, and writes each spec by mirroring code that already exists in the repo.

It runs as a loop:

The loop runs until the developer is satisfied — and only then does coding begin. Design issues get caught here, on cheap text artifacts, instead of in a PR review after the code is already written.

Phase 5 — AI-Assisted Coding Loop

Owner: Developer + Claude.

Because the specs and plan were already settled, this loop is mostly mechanical. The drawer feature above came together in well under an hour of wall time and roughly 3,000 lines of code — all matching a spec the whole team had already agreed on.

Phase 6 — QA, Documentation & Release

Owner: QA.

• QA executes the test plan it created back in Phase 3.
• Visual QA (VQA) validates the UI against the Final UI Specification.
• Any issues loop back to the Dev Review stage.
• Claude analyzes which docs need updating after implementation.
• On pass → PROD deployment.

That documentation step matters more than it looks. After the feature ships, Claude runs a documentation impact analysis: it scans which SRS files, API docs, and analytics specs drifted, classifies each as a major/minor/no-change update, and proposes the exact edits — so the docs that started the process stay correct for the next one.

After release, real-world feedback flows back to Product, closing the loop.

What Actually Changes

Stripped to the essentials, D3 moves three things earlier in time:

• The spec stops being a write-up of what was built and becomes the input that drives the build. The discussion’s output is the spec.
• QA stops testing after the fact and starts writing the test plan from the draft SRS — so test design happens before, not after, implementation.
• AI stops being a coding assistant at the end and becomes a participant at every phase: it gathers requirements, drafts specs, plans, implements, reviews, and flags doc drift.

Everything else — predictable scope, fewer re-scoping conversations, cheaper reviews — falls out of those three shifts. The net effect is less rework and features that ship closer to what was actually intended.

A Note on Tooling

I describe this with Claude and a specific set of skills because that’s what we used, but D3 is model-agnostic. Nothing in the process depends on a particular vendor — it needs an LLM agent that can read your codebase, search the web, follow a multi-step prompt, and ideally call tools (a code/docs explorer, a design integration). Any capable model fits: Claude, GPT, Gemini, or a local model behind an agent runtime like Cursor, Aider, or your own scripts.

What matters is the capabilities, not the brand: codebase awareness so specs reference real modules, a long enough context window to hold the consolidated requirements, and tool access so the agent validates against reality instead of hallucinating. Swap the model; the seven phases stay the same. Quality and speed will vary by model, so treat the numbers above as one data point, not a benchmark.

Getting Started

1. Pilot on the next new feature — run D3 end-to-end as a trial.
2. Set up the skills — plan-feature, implement-feature, and a PR-review skill.
3. Configure the tools — code/docs exploration and the Figma MCP.
4. Establish SRS templates — a consistent structure for the UI / Server / Client specs.
5. Review the pilot — collect feedback, measure the time saved, and refine the process.

D3 is not a rigid framework — it’s a discipline. The goal is simple: by the time anyone writes code, everyone already knows exactly what we’re building.

«Если фича не задокументирована — её не существует. Если она задокументирована неправильно — значит, она сломана».

Большинство команд пишут спецификации так же, как пишут тесты к легаси-коду: задним числом, для галочки. Настоящие проектные решения рождаются в переписке в Slack, в комментарии к макету в Figma, в чьей-то голове на стендапе. К тому моменту, когда что-то наконец доходит до бумаги, код уже написан, и документ оказывается лишь описанием сделанного — а не планом того, что предстоит сделать.

«Спецификация раньше кода» — идея не новая. Подходы вроде README-Driven Development (RDD — ввёл Том Престон-Вернер в 2010 году) и «документация прежде всего» существуют больше десяти лет, и все они упирались в одно и то же: написать полную и точную спецификацию вручную долго и скучно, поэтому команды этот шаг попросту пропускали. Дисциплина была правильной — не сходилась экономика.

Изменилось вот что: теперь бо́льшую часть этой дорогой работы берёт на себя LLM-агент — он читает кодовую базу, находит пробелы, расспрашивает команду, готовит черновик спецификации, а затем по ней же пишет код. Documentation Driven Development (D3) — это та самая старая дисциплина, ставшая дешёвой: команда готовит полную спецификацию до написания кода, а ИИ вплетён в каждый этап, а не только в финальное кодирование. В этом посте я разбираю весь процесс целиком на примере фичи, которую мы действительно так выпустили.

Если вы читали мой предыдущий пост Документация в эпоху ИИ, то D3 можно считать процессным продолжением той же мысли: если документация — это новый исходный код, то D3 — выстроенный вокруг неё процесс разработки.

Какую проблему мы решаем

Симптомы вы и так знаете: спецификации, размазанные по Slack, Figma и головам сотрудников; QA, который подключается уже после того, как код написан; ИИ, к которому обращаются при кодировании, но никогда — при планировании. Не буду на этом задерживаться.

Стоит запомнить лишь одно — про экономику. Неверное предположение, замеченное на этапе спецификации, стоит одного предложения; замеченное на код-ревью — целой ветки; замеченное в проде — инцидента. Чем дольше живёт недопонимание, тем дороже его исправлять, — поэтому самый выигрышный ход — перенести самые трудные размышления как можно ближе к началу. Раньше команды так не делали по простой причине: ранние, проработанные спецификации обходились слишком дорого. Ставка D3 в том, что ИИ изменил этот расклад.

Что такое D3?

D3 — это процесс, в котором команда готовит полную спецификацию фичи до написания кода. Вот что это даёт каждой стороне:

Главный сдвиг в том, что спецификация — не бумажка, которую пишут попутно с работой. Она и есть работа — вплоть до момента, когда начинается генерация кода.

Сквозной процесс

Каждая стрелка ниже — это контрольная точка, и обратная связь может вернуться на любой из этапов.

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

Product (идея → PRD → прототип)
        │
        ▼
Сбор требований  ←──────── Обратная связь
  [Аналитик/Technical Project manager + другие команды]
        │
        ▼
Черновик SRS ── Ревью (все стейкхолдеры + QA)
        │
        ▼
Финальный SRS (утверждён)  ───→  QA → Тест-план
        │                        (разработка идёт параллельно)
        ▼
ИИ генерирует спеки реализации (SRS × 3)
  UI SRS · Server SRS · Client SRS
  [ИИ-план ↔ ИИ-ревью → Ревью разработчика]
        │
        ▼
ИИ-код ↔ ИИ-ревью → Ревью разработчика
        │
        ▼
QA / VQA → PROD → Обратная связь

Пройдёмся по этапам.

Этап 1 — Идея и инициация

Ответственный: Product. Этот этап остаётся таким же, как в привычной работе большинства команд. Product берёт бизнес-потребность, запрос пользователя или стратегическую цель и превращает их в связку идея → PRD → прототип. Достаточно лёгкого PRD и/или прототипа — он напрямую питает этап сбора требований. В D3 меняется всё, что происходит после этого этапа.

Этап 2 — Сбор требований

Ответственный: Аналитик/Technical Project manager. Время: ~20 минут, с помощью ИИ.

Именно здесь ИИ впервые по-настоящему окупается. Процесс состоит из трёх шагов:

1. Свести все источники в один файл .md — PRD, макеты, существующую документацию, API-контракты.
2. Claude ищет пробелы — сверяет документацию с существующей кодовой базой, выявляет белые пятна и собирает список открытых вопросов.
3. Claude расспрашивает команду — задаёт точечные вопросы, чтобы закрыть пробелы, и выдаёт чистовой черновик.

Важная деталь: Claude не строит догадки на основе одного лишь PRD. С помощью инструментов изучения кода и документации, а также Figma MCP он читает настоящую кодовую базу и сверяет требования с тем, что уже реализовано. Он знает, какие модули существуют, какие паттерны стоит переиспользовать и куда встроится новая фича.

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

Этап 3 — Ревью и утверждение финального SRS

Ответственные: Аналитик/Technical Project manager + QA + стейкхолдеры.

Черновой SRS из этапа 2 разбирают всей командой, пока его не утвердят все. Результат — единый финальный SRS, согласованный со всеми стейкхолдерами. Как только он утверждён, сразу происходят две вещи:

• QA пишет тест-план прямо по финальному SRS. Тесты продумываются до начала реализации, поэтому баги ловятся в спецификации, а не в коде.
• Разработка может стартовать параллельно. Финального SRS достаточно, чтобы начать; детальные спеки по доменам (следующий этап) старт не блокируют.

Хороший финальный SRS содержит:

• Требования к фиче и критерии приёмки
• Граничные случаи и обработку ошибок
• API-контракты и потоки данных
• Цепочки фолбэков и зависимости

Как выглядит финальный SRS

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

В модуле feature-promo-banners сделать drawer со списком партнёров из API. Реализацию drawer переиспользовать из feature-item-details. Drawer открывается только по deep link.

Цепочка фолбэков:

1. Основной сценарий: запустить промо-действие (основной партнёрский поток).
2. Фолбэк 1: открыть Quick Access Drawer.
3. Фолбэк 2: перейти на экран «Все партнёры».

Критерии приёмки:

• Если основной промо-API падает (используется захардкоженный конфиг) — продолжать показывать скелетон и вызвать Drawer API.
• Если Drawer API отвечает успешно → показать баннер; по тапу открывается Quick Access Drawer.
• Если Drawer API тоже падает → показать баннер; по тапу — переход на /partners.

Именно на таком уровне детализации команда договаривается до того, как LLM сгенерирует хоть строчку спецификации реализации или кода. Не остаётся ни одной неоднозначности, которую разработчику — или модели — пришлось бы домысливать.

Этап 4 — Спеки реализации, сгенерированные ИИ (SRS × 3)

Ответственные: разработчик + Claude.

Финальный SRS говорит, что делать, но ещё не описывает, как. Это следующий шаг — и здесь за дело берётся LLM. С помощью скилла plan-feature (плюс инструменты изучения кода и документации и Figma MCP) Claude разворачивает финальный SRS в три детальные спецификации реализации по доменам:

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

Этап идёт циклом:

Цикл повторяется, пока разработчика всё не устроит, — и только тогда начинается кодирование. Ошибки проектирования отлавливаются здесь, на дешёвых текстовых артефактах, а не на ревью PR, когда код уже написан.

Этап 5 — Цикл кодирования с ИИ

Ответственные: разработчик + Claude.

Поскольку спеки и план уже согласованы, этот цикл по большей части механический. Ту самую фичу с drawer собрали заметно меньше чем за час реального времени и примерно в три тысячи строк кода — и всё это соответствует спецификации, которую вся команда уже согласовала.

Этап 6 — QA, документация и релиз

Ответственный: QA.

• QA прогоняет тест-план, который сам же и составил ещё на этапе 3.
• Визуальный QA (VQA) сверяет UI с финальной UI-спецификацией.
• Любые найденные проблемы возвращаются на этап ревью разработчика.
• Claude анализирует, какую документацию нужно обновить после реализации.
• Если всё проходит → деплой в PROD.

Шаг с документацией важнее, чем кажется. После выхода фичи Claude проводит анализ влияния на документацию: проверяет, какие файлы SRS, API-документация и спецификации аналитики разошлись с реальностью, помечает каждое изменение как крупное, мелкое или ненужное и предлагает конкретные правки — чтобы документация, с которой всё началось, оставалась актуальной к следующему разу.

После релиза реальная обратная связь от пользователей возвращается к Product — и цикл замыкается.

Что в итоге меняется

Если свести к сути, D3 сдвигает раньше по времени три вещи:

• Спецификация перестаёт быть отчётом о сделанном и становится исходными данными, из которых вырастает разработка. Результат обсуждения — это и есть спецификация.
• QA перестаёт тестировать постфактум и начинает писать тест-план уже по черновику SRS — то есть тесты продумываются до реализации, а не после.
• ИИ перестаёт быть помощником-кодером в самом конце и становится участником каждого этапа: собирает требования, пишет спецификации, планирует, реализует, ревьюит и отмечает расхождения в документации.

Всё остальное — предсказуемый объём, меньше разговоров «давайте всё пересмотрим», более дешёвые ревью — вытекает уже из этих трёх сдвигов. Итог: меньше переделок и фичи, которые выходят ближе к тому, что задумывалось.

Несколько слов об инструментах

Я описываю всё на примере Claude и конкретного набора скиллов, потому что именно ими мы пользовались, но D3 не привязан к конкретной модели. В процессе нет ничего, что зависело бы от вендора, — нужен LLM-агент, который умеет читать вашу кодовую базу, искать в интернете, выполнять многошаговый промпт и, желательно, вызывать инструменты (для изучения кода и документации, для работы с дизайном). Подойдёт любая достаточно сильная модель: Claude, GPT, Gemini или локальная модель внутри агентного окружения вроде Cursor, Aider или ваших собственных скриптов.

Важны возможности, а не бренд: знание кодовой базы, чтобы спецификации ссылались на реальные модули; достаточно длинный контекст, чтобы вместить все сведённые требования; и доступ к инструментам, чтобы агент сверялся с реальностью, а не выдумывал. Поменяйте модель — семь этапов останутся прежними. Качество и скорость от модели к модели будут разными, так что считайте цифры выше одним частным примером, а не эталоном.

С чего начать

1. Обкатайте на следующей новой фиче — пройдите D3 от начала до конца как пробный заход.
2. Настройте скиллы — plan-feature, implement-feature и скилл для ревью PR.
3. Подключите инструменты — изучение кода и документации, Figma MCP.
4. Заведите шаблоны SRS — единую структуру для UI / Server / Client спецификаций.
5. Разберите результаты пилота — соберите обратную связь, оцените сэкономленное время и доработайте процесс.

D3 — это не жёсткий фреймворк, а дисциплина. Цель простая: к тому моменту, когда кто-то садится писать код, все уже точно знают, что именно мы делаем.

Но написать документацию — это только половина дела: сразу за этим всплывают две проблемы, и именно им посвящён остаток статьи.

• Хорошую документацию не читают, когда до неё трудно добраться. Ответ на вопрос «как работает фича X?» обычно уже лежит где-то в docs/ или в коде, но чтобы его найти, нужно знать репозиторий наизусть. Поэтому проще спросить коллегу — а коллега бросает свою работу и заново объясняет то, что в репозитории давно описано.
• Документация устаревает. Стоит коду измениться, как документация тихо перестаёт быть правдой. Этот сбой никогда не вылезает стектрейсом — он проявляется как «агент (или новый сотрудник) сделал не то», а такую причину куда труднее отследить и куда дороже обнаружить.

Две системы ниже бьют ровно по этим проблемам: мультиагентный Chat с документацией, который делает документацию и код мгновенно доступными для запросов, и автоматический конвейер Jira → Docs, который держит их актуальными. Обе предполагают, что документация, которую стоит поддерживать, у вас уже есть, — они усиливают эту вложенную работу, а не заменяют её. И обе описаны достаточно конкретно, чтобы их можно было повторить.

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

Chat с документацией напрямую решает первую проблему: он превращает уже существующую документацию в то, у чего можно спрашивать, — прямо там, где команда и так общается. Стоит подчеркнуть: это окупается именно потому, что документация есть. Он усиливает вложения в документацию, а не позволяет их пропустить: направьте его на пустую docs/ — и получите разве что красноречивый способ сказать «я не знаю».

Это один «мозг» за несколькими интерфейсами: веб-приложением на рабочем месте и чат-ботом. И там, и там любой член команды может задать вопрос по кодовой базе и получить потоковый ответ со ссылками на источники. Бот начинался в Slack, но в нём нет ничего, завязанного именно на Slack: тот же бэкенд точно так же поднимает Telegram-бота, а в принципе подключается любая платформа с API для ботов (Discord, Microsoft Teams, …). Приходите к людям туда, где они уже общаются, а не заставляйте открывать ещё один инструмент.

Самое интересное здесь — то, чем Chat с документацией сознательно не является: это не RAG-конвейер на эмбеддингах. Это мультиагентная система, которая ищет по документации и коду параллельно, используя файловые инструменты, уже встроенные в Claude Agent SDK.

1
2
3
4
5

Клиент (Lit + Vite)          Сервер (Express + Agent SDK)
  UI чата, рендеринг     ──►  Агент-оркестратор
  markdown, SSE              ├── Агент документации (дерево docs)
                            ├── Агент кода (ripgrep по репозиторию)
                            └── Агент-ответчик (синтез ответа)

• Оркестратор — разбирает вопрос, раздаёт подзадачи, собирает результаты воедино.
• Агент документации — ищет по дереву docs инструментами SDK (Read, Glob, Grep).
• Агент кода — гоняет ripgrep по репозиторию.
• Агент-ответчик — собирает финальный ответ для пользователя.

На стороне клиента связка Lit + TypeScript + Vite держит вес фреймворка меньше 5 КБ и обходится без виртуального DOM; ответы приходят потоком через Server-Sent Events; markdown рендерится через marked + DOMPurify + highlight.js. Сервер — это Express плюс @anthropic-ai/claude-agent-sdk, разворачивается через Docker Compose.

Почему без векторной БД? На корпусе такого размера агент, который делает grep по живой файловой системе, всегда видит актуальное состояние репозитория. Индекс эмбеддингов, наоборот, хранит снимок — и стоит коду измениться, как этот снимок устаревает, пока кто-нибудь заново не пересчитает эмбеддинги и не синхронизирует индекс. Этот цикл «посчитать — синхронизировать — снова устарело» и есть та самая нагрузка на сопровождение, которая тихо убивает большинство RAG-систем. А выигрыша от него нет: Glob и Grep и так отвечают на вопрос. Поэтому индекс мы не строим — пусть агент ищет сам. Запуск в виде чат-бота дополнительно снижает порог входа: не нужно уходить из Slack или Telegram, чтобы спросить «а как работает X?».

Конвейер автообновления: поддерживаем мозг в форме

Chat с документацией полезен ровно настолько, насколько актуальна документация, которую он читает, — поэтому вторая система занимается тем, что поддерживает эту документацию свежей автоматически. Workflow в GitHub Actions запускается в тот момент, когда тикет в Jira переходит из Tech Review в Ready for Dev — то есть как только зафиксирован объём работ, но ещё до того, как написана хоть строчка кода. Именно момент запуска здесь неочевиден: обычно команды обновляют документацию, когда тикет уже в Done, а значит, пишут её задним числом, спустя недели, когда контекст уже выветрился. Запуск на Ready for Dev кладёт документацию рядом со спецификацией, пока всё свежо в голове, и заодно даёт разработчику задокументированную цель, под которую он будет писать код.

Конвейер состоит из четырёх типизированных стадий, и главная идея — соизмерять стоимость модели со сложностью задачи, а не натравливать одного большого агента на всё подряд:

1. Сортировка (дешёвая модель + MCP). Модель уровня Haiku забирает тикет через automation MCP, прогоняет его через фильтры по полям и решает, нужна ли вообще документация. Багфиксы, обновления зависимостей и рефакторинги она пропускает — около $0.001 за запуск, так что 90% тикетов отсеиваются за десятую долю цента ещё до того, как проснётся дорогая модель.
2. Основной агент. Обычная (сильная) модель работает с репозиторием кода как с рабочей директорией, поэтому сама подхватывает CLAUDE.md и .claude/. Она читает индекс документации, сопоставляет изменённые модули с документами, правит файлы и делает коммит — но пока не пушит.
3. Агент-ревьюер. Второй проход сильной модели смотрит на git diff HEAD~1 и проверяет правила качества: никаких бизнес-метрик, никакого пересказа кода своими словами, достаточное покрытие логики. На выходе — список замечаний в JSON.
4. Исправление и PR. Если замечания есть, агент-исправитель вносит правки, после чего workflow пушит ветку docs/jira-<ticket> и открывает (или обновляет) PR.

Фильтры, которые управляют первой стадией, — это просто данные, поэтому всю систему можно настраивать, не трогая код агентов:

1
2
3
4
5
6
7

// config.ts — какой тикет считаем требующим документации
export const filters = {
  issueTypes: ["Task"],                 // [] = разрешить все
  projects: ["AND"],
  requiredLabels: [],
  excludedLabels: ["no-docs", "found_by_automation"],
};

Это тот самый паттерн, который Anthropic рекомендует в Building Effective Agents: сортируем дёшево, работаем сильной моделью, проверяем сильной моделью, исправляем только когда нужно. Затраты предсказуемы, сбои локальны, а каждую стадию можно тестировать отдельно — полная противоположность одному агенту, который бесконечно крутится вокруг огромного набора инструментов.

Что делает репозиторий понятным для агента

Обе системы стоят на одном фундаменте: репозиторий устроен так, что агент ориентируется в нём без догадок. Основную работу делают три файла.

CLAUDE.md в корне репозитория подгружается в каждую сессию агента автоматически. Воспринимайте его как загрузочный конфиг для новичка, которым оказалась модель: коротко, по делу, без воды.

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

# CLAUDE.md

## Сборка и тесты
- Сборка: ./gradlew assembleDebug
- Тесты:  ./gradlew testDebugUnitTest
- Линт:   ./gradlew ktlintCheck

## Соглашения
- Одна фича — один модуль в :features/<name>
- ViewModel отдаёт единый UiState; никакого LiveData в новом коде
- Результаты сетевых запросов оборачиваем в AppResult<T>, без «голых» исключений

## Подводные камни
- Экраны с WebView обязаны использовать SafeWebViewClient (см. .claude/rules/webview.md)
- После правки strings.xml запускайте ./scripts/gen-translations.sh

.claude/rules/*.md хранят узкие тематические правила, которые ездят вместе с кодом (по файлу на тему: webview.md, app-result.md, …). Субагент читает нужное правило как готовый чек-лист, а не выводит соглашения заново при каждом запуске.

Индекс документации (docs/INDEX.md или формат llms.txt) связывает модули с их документами, чтобы первым шагом агента всегда было «посмотреть, где это лежит», а не слепой поиск. Именно этот единственный переход и позволяет каждому скилу ниже стартовать с нужного документа.

Документация питает каждый скил

Когда фундамент есть, скилы — переиспользуемые именованные процедуры, которые вызывает агент (/implement-feature, /task-worker, /check-coverage), — все работают по одной схеме: сначала прочитать нужный документ, потом действовать.

• task-worker забирает тикет из Jira, по индексу документации находит папку фичи, открывает её спецификацию и пишет план, опираясь на задокументированное поведение.
• implement-feature сначала ищет уже существующие паттерны в документации, чтобы новый код ложился в принятые соглашения, а не изобретал свои.
• review-pr-advanced запускает узкоспециализированных субагентов (архитектура, Compose, структура пакетов, тесты, производительность), и каждый берёт за основу свой .claude/rules/*.md.
• check-coverage гоняет JaCoCo и по документации модулей понимает, что вообще должно быть покрыто тестами, — и пишет осмысленные тесты, а не ради процента покрытия.

Инвариант простой: скил хорош ровно настолько, насколько хороша документация, которую он читает. В день, когда документация начинает гнить, тихо деградирует каждый скил — незаметно, потому что код всё ещё компилируется.

Идея под капотом: Software 3.0

Ничто из этого не завязано на конкретный стек — всё это следствие сдвига, который чётко описали два человека.

Андрей Карпаты называет это Software 3.0: после 1.0 (код, написанный руками) и 2.0 (обученные веса) программы теперь отчасти задаются промптами на естественном языке к LLM. В такой картине код, документация, конфиги и промпты — это всё входные токены, а сама LLM — среда выполнения: контекстное окно как оперативная память, документация как диск. Практический вывод — делать репозиторий удобным для LLM: простой текст, явные соглашения, примеры вместо длинных описаний, один источник истины на каждую фичу, и хранить его в репозитории, а не закапывать в Confluence. Даже «vibe coding», термин самого Карпаты, — это не про отказ от структуры: чем чётче спецификация, тем быстрее сходятся «вайбы».

Рекомендации Anthropic для Claude Code и Agent SDK приходят к тому же с инженерной стороны: понятный структурированный контекст прямо в репозитории работает лучше изощрённых промптов, а попадания в кэш промптов резко падают, когда документация меняется по косметическим поводам, — так что аккуратный текст с низкой текучестью оказывается ещё и способом сэкономить. Оба взгляда сводятся к одному правилу: дайте агенту тот же контекст, что дали бы сильному инженеру в его первый день, и держите этот контекст в актуальном состоянии.

Это не привязано к одной модели

В примерах выше используется Claude Agent SDK — просто потому, что эти системы работают на нём. Но в самом подходе нет ничего, что было бы завязано на Claude. Переносимое здесь — это архитектура:

• Chat с документацией требует LLM, которая умеет в цикле вызывать инструменты (прочитать файл, сделать grep, решить, что читать дальше) и отдавать ответ потоком. Любая модель с function calling за любым агентным фреймворком — SDK от OpenAI, LangChain/LangGraph, локальная модель через Ollama с обёрткой под tool use — без изменений встаёт на роли оркестратора, агента документации, агента кода и ответчика. А решение «никакой векторной БД, просто grep по живому репозиторию» от модели не зависит вовсе.
• Конвейер для Jira — это workflow, разнесённый по стоимости: дешёвая модель сортирует, сильная пишет, сильная проверяет. Подставьте любую пару «дешёвая/сильная» от вашего провайдера — границы стадий, передача данных через JSON и момент запуска останутся теми же.
• Соглашения в репозитории переносятся легче всего. CLAUDE.md — это просто имя файла, который автоматически читает Claude Code; сама идея — корневой файл с контекстом, тематические файлы правил, индекс документации — работает с любым агентом. Другие инструменты читают свои аналоги (AGENTS.md, .cursorrules, llms.txt), и их можно сделать симлинками или генерировать из одного источника, чтобы все модели читали одну и ту же правду.

Если коротко: берите модель под свой бюджет и требования к приватности. Рычаг дают документация и форма workflow, а не вендор.

Итог

В мире Software 3.0 документация — уже не вежливая формальность, какой она была в 2010-х. Это часть программы, и устаревает она ровно в тот момент, когда код уезжает у неё из-под ног. Две описанные системы — рабочий ответ на это: Chat с документацией позволяет запрашивать этот «мозг», не таская за собой векторную БД, а конвейер Jira держит «мозг» честным, записывая документацию, пока контекст ещё свежий. Обе стоят на одном и том же дешёвом и непримечательном фундаменте — CLAUDE.md, несколько файлов с правилами и индекс документации — и обе окупаются на каждом следующем запуске агента.

Что почитать дальше

• Андрей Карпаты — Software 2.0 (2017) и его доклады «Software 3.0 / LLM OS» (2024–2025)
• Anthropic — Building Effective Agents (декабрь 2024)
• Anthropic — Claude Code best practices
• Model Context Protocol — открытый протокол для подключения инструментов к LLM-агентам
• llms.txt — соглашение о машиночитаемой точке входа в репозиторий

But writing docs is only half the battle — two problems show up right after, and they are the ones the rest of this post is about.

• Good docs go unread when they are hard to reach. The answer to “how does feature X work?” is usually already in docs/ or the code, but finding it means knowing the repo by heart. So people ping a colleague instead, and that colleague stops their own work to re-explain something the repo already documents.
• Docs drift. The moment code changes, the docs quietly stop being true. That failure never surfaces as a stack trace — it surfaces as “the agent (or the new hire) did the wrong thing,” which is far harder to attribute and much more expensive to discover.

The two systems below attack exactly these: a multi-agent Doc-Chat that makes your docs and code instantly queryable, and an automated Jira → Docs pipeline that keeps them current. Both assume you already have documentation worth maintaining — they amplify that investment, they don’t replace it. And both are concrete enough to copy.

Doc-Chat: Multi-Agent Q&A Over Docs and Code

Doc-Chat directly solves the first problem: it turns existing documentation into something you can ask questions of, in the place where the team already talks. It is worth stressing that this only pays off because the docs exist — Doc-Chat is an amplifier on a documentation investment, not a way to skip it. Point it at an empty docs/ and you get an eloquent way to say “I don’t know.”

It is one brain behind several interfaces: a web app at the desk and a chat bot. Both let any team member ask a question about the codebase and get a sourced, streamed answer. The bot started in Slack, but nothing about it is Slack-specific — the same backend drives a Telegram bot just as well, and in principle any platform with a bot API (Discord, Microsoft Teams, …) plugs into the same place. Meet people where they already chat instead of asking them to open one more tool.

The interesting decision is what it isn’t: it is intentionally not a RAG pipeline with embeddings. It is a multi-agent system that searches docs and code in parallel using the filesystem tools the Claude Agent SDK already provides.

1
2
3
4
5

Client (Lit + Vite)          Server (Express + Agent SDK)
  chat UI, markdown      ──►  Orchestrator Agent
  rendering, SSE              ├── Docs Agent  (docs tree)
                             ├── Code Agent  (ripgrep over repo)
                             └── Answer Agent (synthesizes)

• Orchestrator — routes the question, fans out, merges results.
• Docs Agent — searches the docs tree via SDK tools (Read, Glob, Grep).
• Code Agent — runs ripgrep over the repo.
• Answer Agent — synthesizes the final user-facing response.

On the client side, Lit + TypeScript + Vite keeps the framework under 5 KB with no virtual DOM; answers stream over Server-Sent Events; markdown is rendered with marked + DOMPurify + highlight.js. The server is Express plus @anthropic-ai/claude-agent-sdk, deployed via Docker Compose.

Why no vector DB? On a corpus this size, an agent that greps the live filesystem always reads the current state of the repo. An embedding index reads a snapshot — and the moment code changes, that snapshot is stale until someone re-embeds and re-syncs it. The embed/sync/staleness loop is exactly the maintenance burden that quietly kills most RAG systems, and it buys you nothing when Glob + Grep already answer the question. Skip the index; let the agent search. Running it as a chat bot lowers the activation cost even further: nobody has to leave Slack or Telegram to ask “how does X work?”

The Auto-Update Workflow: Keeping the Brain Healthy

Doc-Chat is only as good as the docs it reads, so the second system keeps those docs fresh automatically. A GitHub Actions workflow fires the moment a Jira ticket transitions from Tech Review → Ready for Dev — that is, as soon as scope is locked and before a line of code is written. That timing is the non-obvious part: most teams reach for “update docs when the ticket is Done,” which means docs are written retroactively, weeks later, when nobody remembers the context. Triggering at Ready for Dev lands the docs alongside the spec while the reasoning is fresh, and gives the implementing engineer a documented target to build against.

The pipeline has four typed stages — and the key idea is matching model cost to task difficulty rather than throwing one big agent at everything:

1. Triage (cheap model + MCP). A Haiku-class model fetches the ticket via an automation MCP, applies field filters, and decides whether docs are even needed. It skips bug fixes, dependency bumps, and refactors — roughly $0.001 per run, so 90% of tickets are rejected for a tenth of a cent before any expensive model wakes up.
2. Main agent. The default (strong) model runs with the code repo as its working directory, so it automatically loads CLAUDE.md and .claude/. It reads the docs index, maps changed modules to docs, edits files, and commits — but does not push yet.
3. Review agent. A second strong-model pass looks at git diff HEAD~1 and checks quality rules: no business metrics, no trivial restatement of code, adequate logic coverage. Returns a JSON list of issues.
4. Fix & PR. If issues were found, a fix agent applies corrections, then the workflow pushes to a docs/jira-<ticket> branch and opens (or updates) a PR.

The filter config that gates stage 1 is just data, which makes the whole thing tunable without touching agent code:

1
2
3
4
5
6
7

// config.ts — what counts as a docs-worthy ticket
export const filters = {
  issueTypes: ["Task"],                 // [] = allow all
  projects: ["AND"],
  requiredLabels: [],
  excludedLabels: ["no-docs", "found_by_automation"],
};

This is the workflow pattern Anthropic recommends in Building Effective Agents: triage cheap, work strong, review strong, fix only when needed. Cost stays predictable, failures stay localized, and each stage is independently testable — the opposite of a single agent looping over a giant tool surface.

What Makes a Repo Agent-Readable

Both systems lean on the same foundation: a repo laid out so an agent can navigate it without guessing. Three files do most of the work.

CLAUDE.md at the repo root is loaded into every agent session automatically. Treat it as the boot config for a new hire who happens to be a model — terse, factual, no marketing:

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

# CLAUDE.md

## Build & test
- Build:  ./gradlew assembleDebug
- Test:   ./gradlew testDebugUnitTest
- Lint:   ./gradlew ktlintCheck

## Conventions
- One feature per module under :features/<name>
- ViewModels expose a single UiState; no LiveData in new code
- Network results wrapped in AppResult<T>, never raw exceptions

## Gotchas
- WebView screens must use SafeWebViewClient (see .claude/rules/webview.md)
- Run ./scripts/gen-translations.sh after editing strings.xml

.claude/rules/*.md hold narrow, topical guidelines that travel with the code (one file per concern: webview.md, app-result.md, …). Sub-agents read the relevant rule as their rubric instead of re-deriving conventions every run.

A docs index (docs/INDEX.md, or the llms.txt convention) maps modules to their docs so an agent’s first step is always “look up where this lives,” not a blind search. This single hop is what lets every skill below start from the right document.

Docs Power Every Skill

Once that foundation exists, skills — reusable, named procedures the agent invokes (/implement-feature, /task-worker, /check-coverage) — all share one pattern: read the relevant doc, then act.

• task-worker fetches a Jira ticket, reads the docs index to find the feature folder, opens its spec, then writes a plan grounded in the documented behavior.
• implement-feature discovers existing patterns through docs first, so new code matches documented conventions instead of inventing its own.
• review-pr-advanced spawns specialist sub-agents (architecture, Compose, package structure, tests, performance), each reading the relevant .claude/rules/*.md as its rubric.
• check-coverage runs JaCoCo and uses module docs to understand what should be tested — so it writes meaningful tests, not coverage-padding ones.

The invariant: every skill is only as good as the docs it consumes. The day docs rot is the day every skill silently degrades — invisibly, because the output still compiles.

The Idea Underneath: Software 3.0

None of this is specific to one stack; it follows from a shift two people have named clearly.

Andrej Karpathy frames it as Software 3.0 — after 1.0 (handwritten code) and 2.0 (learned weights), programs are now partly expressed as natural-language prompts to an LLM. In that view your code, docs, configs, and prompts are all input tokens, and the LLM is the runtime: the context window is RAM, your docs are the disk. The practical corollary is to make the repo LLM-friendly — plain text, explicit conventions, examples over prose, one source of truth per feature kept in the repo, not buried in Confluence. Even “vibe coding,” his own term, isn’t an argument against structure: clearer specs make the vibes converge faster.

Anthropic’s guidance for Claude Code and the Agent SDK lands in the same place from the engineering side: clear, structured, repo-resident context beats clever prompting, and prompt-cache hit rates collapse when docs churn for cosmetic reasons — so high-quality, low-churn writing is also a cost optimization. Both views reduce to one instruction: give the agent the same context you’d give a senior engineer on day one, and keep it true.

This isn’t tied to one model

The examples above use the Claude Agent SDK because that’s what these systems run on, but nothing in the approach is Claude-specific. The architecture is the portable part:

• Doc-Chat needs an LLM that can call tools in a loop (read a file, grep, decide what to read next) and stream tokens. Any function-calling model behind any agent framework — OpenAI’s SDK, LangChain/LangGraph, a local model via Ollama with a tool-use wrapper — slots into the orchestrator/docs/code/answer roles unchanged. The “no vector DB, just grep the live repo” decision is model-independent entirely.
• The Jira pipeline is a cost-tiered workflow: a cheap model triages, a strong model writes, a strong model reviews. Swap in whatever cheap/strong pair your provider offers — the stage boundaries, the JSON hand-offs, and the trigger timing don’t change.
• The repo conventions are the most portable of all. CLAUDE.md is just the filename Claude Code auto-loads; the underlying idea — a root context file, topical rule files, a docs index — works for any agent. Other tools read their own equivalents (AGENTS.md, .cursorrules, llms.txt), and you can symlink or generate them from a single source so every model reads the same truth.

In short: pick the model that fits your budget and privacy constraints. The leverage comes from the docs and the workflow shape, not the vendor.

Bottom Line

In a Software-3.0 world, docs are not the polite afterthought they were in the 2010s — they are part of the program, and they decay the moment the code moves underneath them. The two systems here are a working answer to that: Doc-Chat lets you query the brain without a vector DB to maintain, and the Jira pipeline keeps the brain honest by writing docs while the context is still fresh. Both rest on the same cheap, unglamorous foundation — a CLAUDE.md, a few rules files, and a docs index — and both pay for themselves on every future agent run.

Further Reading

• Andrej Karpathy — Software 2.0 (2017), and his “Software 3.0 / LLM OS” talks (2024–2025)
• Anthropic — Building Effective Agents (Dec 2024)
• Anthropic — Claude Code best practices
• Model Context Protocol — the open protocol for plugging tools into LLM agents
• llms.txt — a machine-readable entry-point convention for repos

Шаг 1. Установка

1
2

sudo apt update
sudo apt install asterisk

Проверьте, что Asterisk запустился (Вы должны увидеть “active (running)”)

1

sudo systemctl status asterisk

Шаг 2. Настройка аккаунтов

В sudo nano /etc/asterisk/pjsip.conf

Добавьте конфигурацию:

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
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

[transport-udp]
type=transport
protocol=udp
bind=0.0.0.0:5060 ; вы можете изменить порт по умолчанию
external_media_address=[IP адрес VPS]
external_signaling_address=[IP адрес VPS]
local_net=192.168.0.0/16 ;опционально
local_net=10.0.0.0/8 ;опционально

; ----- Пользователь 1 -----
[1001]
type=endpoint
context=internal
disallow=all
allow=ulaw
auth=1001
aors=1001
direct_media=no ; Принудительная маршрутизация RTP через Asterisk
rtp_symmetric=yes ; Важно для NAT
force_rport=yes ; Важно для NAT
rewrite_contact=yes ; Важно для NAT

[1001]
type=auth
auth_type=userpass
password=strongpassword1
username=1001

[1001]
type=aor
max_contacts=1
remove_existing=yes

; ----- Пользователь 2 -----
[1002]
type=endpoint
context=internal
disallow=all
allow=ulaw
auth=1002
aors=1002
direct_media=no ; Принудительная маршрутизация RTP через Asterisk
rtp_symmetric=yes ; Важно для NAT
force_rport=yes ; Важно для NAT
rewrite_contact=yes ; Важно для NAT
media_encryption=sdes  ; Включить SRTP для шифрованного аудио, может не поддерживаться на старых устройствах, установите no для старых устройств или приложений. Или sdes, или dtls, или srtp

[1002]
type=auth
auth_type=userpass
password=strongpassword2
username=1002
;realm=[ваш домен] ; в некоторых случаях, если вы установили default-realm, нужно установить то же самое для всех клиентов

[1002]
type=aor
max_contacts=1
remove_existing=yes
qualify_frequency=60
maximum_expiration=3600
minimum_expiration=60

; Повторите, если нужно больше пользователей

Объяснение ключевых параметров:

• type=endpoint - Определяет SIP конечную точку
• context=internal - Какой контекст диалплана использовать
• auth=1001 - Ссылка на секцию аутентификации
• aors=1001 - Ссылка на AOR (Address of Record)
• max_contacts=1 - Сколько устройств может одновременно зарегистрироваться
• remove_existing=yes - Заменяет старую регистрацию при новом входе
• direct_media=no - Принудительная маршрутизация RTP через Asterisk (полезно для NAT)
• media_encryption=no - Шифрование

Опции media_encryption:

• no - Без шифрования
• sdes - SRTP с обменом ключами SDES
• dtls - SRTP с обменом ключами DTLS

Использование опционального шифрования:

1
2

media_encryption=sdes
media_encryption_optimistic=yes ; Разрешить откат к незашифрованному соединению

Определите диалплан в /etc/asterisk/extensions.conf
(Например, любой пользователь может позвонить другому (например, 1001 → 1002).)

1
2
3
4

[internal]
exten => _1XXX,1,Dial(PJSIP/${EXTEN},20)
exten => _1XXX,n,Hangup()

Перезагрузите Asterisk

1
2
3
4
5
6

sudo asterisk -rx "reload"

# ИЛИ

sudo systemctl restart asterisk

Для проверки пользователей

1
2
3

sudo asterisk -rvvv
# затем:
pjsip show endpoints

RTP медиа-порты (Опционально)
Вы можете уменьшить количество портов для RTP
в /etc/asterisk/rtp.conf

1
2
3

[general]
rtpstart=10000
rtpend=20000

Проверка логов

1

sudo asterisk -rvvv

На моём старом Ubuntu сервере мне потребовались дополнительные изменения для использования PJSIP вместо chan_sip (устаревший драйвер канала SIP). Без этих изменений настройки выше не будут работать (потому что настройки для chan_sip должны быть размещены в /etc/asterisk/sip.conf).

Настройка загрузки модуля PJSIP
в /etc/asterisk/modules.conf обновите список модулей для загрузки:

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

[modules]
autoload=yes

; Отключить chan_sip
noload => chan_sip.so

; Убедитесь, что модули PJSIP загружены
load => res_pjsip.so
load => res_pjsip_session.so
load => res_pjsip_registrar.so
load => res_pjsip_outbound_registration.so
load => chan_pjsip.so

STUN

В файле: /etc/asterisk/rtp.conf

добавьте:

1
2
3
4

[general]
rtpstart=10000
rtpend=20000
stunaddr=stun.l.google.com:19302  ; Для обхода NAT

Проверка клиентов:

1
2

asterisk -rx "pjsip show endpoints"
asterisk -rx "pjsip show contacts"

Отладка проблем медиа-согласования

1

asterisk -rvvvvv

Затем в CLI:

1
2

pjsip set logger on
core set debug 5

Сделайте тестовый звонок и следите за:

1
2
3

-- Called PJSIP/1002
-- PJSIP/1002-00000001 is ringing
[NOTICE] res_pjsip_session.c: Incompatible media format - no common codec

Или:

1

WARNING[xxxxx]: res_pjsip_sdp_rtp.c: No common codecs between endpoints

Понимание полей статуса

• Avail - Устройство доступно (qualify успешен)
• Unavail - Устройство не ответило на ping qualify, но звонки всё равно могут работать
• NonQual - Qualify не настроен
• Unknown - Проверки qualify ещё не выполнялись

Важно: Статус влияет на решения по маршрутизации звонков только если вы используете qualify в логике диалплана. Для базовых звонков это не имеет значения!

Настройки безопасности PJSIP

В /etc/asterisk/pjsip.conf:

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

[global]
allow_anonymous=no
max_forwards=70
user_agent=Asterisk PBX
default_realm=[ваш домен]

; ACL для ограничения источников регистрации (опционально, но рекомендуется)
[acl]
type=acl
deny=0.0.0.0/0.0.0.0
permit=IP_ВАШЕГО_ОФИСА/32
permit=IP_ВАШЕГО_ДОМА/32

Отключите ненужные модули в /etc/asterisk/modules.conf

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

[modules]
autoload=yes

; Отключить chan_sip, если используете PJSIP
noload => chan_sip.so

; Отключить ненужные протоколы
noload => chan_skinny.so
noload => chan_mgcp.so
noload => chan_unistim.so

; Отключить веб-интерфейс, если не нужен
noload => res_http_websocket.so
noload => res_ari.so
noload => res_stasis.so

Защита Asterisk Manager Interface (AMI) в /etc/asterisk/manager.conf

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

[general]
enabled = no  ; Отключить, если не нужен
port = 5038
bindaddr = 127.0.0.1  ; Только локальный доступ

; Если вам нужен AMI, используйте сильные учётные данные:
[admin]
secret = VeryStr0ngAMIPass123!
deny = 0.0.0.0/0.0.0.0
permit = 127.0.0.1/255.255.255.0
read = system,call,log,verbose,command,agent,user,config
write = system,call,log,verbose,command,agent,user,config

Проверка подозрительной активности:

1
2
3
4
5

# Проверить неудачные попытки регистрации
asterisk -rx "pjsip show registrations"

# Мониторинг активных каналов
asterisk -rx "core show channels"

SSL

Вариант A: Let’s Encrypt (Бесплатно и рекомендуется)

1
2
3
4
5
6
7
8
9
10

# Установить Certbot
sudo apt update
sudo apt install certbot

# Получить сертификат
sudo certbot certonly --standalone -d [ваш домен]

# Сертификат будет находиться по адресу:
# /etc/letsencrypt/live/[ваш домен]/fullchain.pem
# /etc/letsencrypt/live/[ваш домен]/privkey.pem

Вариант B: Самоподписанный сертификат

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

sudo mkdir -p /etc/asterisk/keys
cd /etc/asterisk/keys

# Сгенерировать приватный ключ и сертификат
sudo openssl req -new -x509 -days 365 -nodes \
  -out asterisk.pem -keyout asterisk.key \
  -subj "/C=RU/ST=State/L=City/O=Organization/CN=s.mdroid.ru"

# Объединить их
sudo cat asterisk.key asterisk.pem > asterisk.combined.pem
sudo chmod 600 asterisk.combined.pem

Установка правильных прав доступа

1
2
3
4
5
6
7

# Для сертификатов Let's Encrypt
sudo chown -R asterisk:asterisk /etc/letsencrypt/
sudo chmod -R 640 /etc/letsencrypt/live/s.mdroid.ru/*.pem

# Для самоподписанных сертификатов
sudo chown asterisk:asterisk /etc/asterisk/keys/*
sudo chmod 600 /etc/asterisk/keys/*

Настройка

В файле: /etc/asterisk/pjsip.conf

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
45
46
47
48
49
50
51
52
53
54

[global]
max_forwards=70
user_agent=Asterisk PBX
default_realm=[ваш домен или asterisk]

; UDP транспорт (оставьте для обратной совместимости)
[transport-udp]
....

; TLS транспорт (безопасный)
[transport-tls]
type=transport
protocol=tls
bind=0.0.0.0:5061
cert_file=/etc/letsencrypt/live/[ваш домен]/fullchain.pem
priv_key_file=/etc/letsencrypt/live/[ваш домен]/privkey.pem
; ИЛИ для самоподписанного:
; cert_file=/etc/asterisk/keys/asterisk.combined.pem
; priv_key_file=/etc/asterisk/keys/asterisk.combined.pem
;cipher=ALL ; используйте только если вы знаете, какой формат поддерживается
method=sslv23 ; или tlsv1_2 для современных устройств
verify_server=no
verify_client=no
external_media_address=[IP сервера]
external_signaling_address=[IP сервера]

; Обновите конечные точки для использования TLS
[1001]
type=endpoint
context=internal
;transport=transport-tls ;опционально, чтобы принудительно использовать TLS
disallow=all
allow=ulaw
allow=alaw
auth=1001
aors=1001
direct_media=no
rtp_symmetric=yes
force_rport=yes
rewrite_contact=yes
media_encryption=sdes  ; Включить SRTP для шифрованного аудио, может не поддерживаться на старых устройствах, установите no для старых устройств или приложений. Или sdes, или dtls

[1001]
type=auth
auth_type=userpass
password=YourStrongPassword
username=1001
;realm=[ваш домен] ; в некоторых случаях, если вы установили default-realm, нужно установить то же самое для всех клиентов

[1001]
type=aor
max_contacts=1
remove_existing=yes
qualify_frequency=60

Перезагрузка:

1
2
3
4
5
6

# Перезагрузка
asterisk -rx "core reload"
asterisk -rx "pjsip reload"

# Проверка работы TLS транспорта
asterisk -rx "pjsip show transports"

Вы должны увидеть вывод вроде:

1
2
3
4

Transport:  <TransportId........>  <Type>  <cos>  <tos>  <BindAddress.....................>
===========================================================================
transport-udp               udp      0      0  0.0.0.0:5060
transport-tls               tls      0      0  0.0.0.0:5061

Если вы не видите transport-tls, проверьте логи:

1

tail -50 /var/log/asterisk/full | grep -i transport

Если вы видите ошибку:

1

ERROR[1069851] res_sorcery_config.c: Could not create an object of type 'transport' with id 'transport-tls' from configuration file 'pjsip.conf'

Проверьте:

• Что путь к файлам сертификатов правильный
• Удалите или измените параметр cipher (у меня работает: cipher=ADH-AES256-SHA,ADH-AES128-SHA)

Для самоподписанных сертификатов вам нужно отключить проверку сертификата на клиенте или добавить в /etc/asterisk/pjsip.conf:

1
2
3

[transport-tls]
....
require_client_cert=no

Why Set JAVA_HOME?

• Required by build tools: Maven, Gradle, and Ant need it to find Java
• Application servers: Tomcat, JBoss, and others use it
• IDE compatibility: Ensures consistent Java version across tools
• Script automation: Makes Java location consistent across systems

Finding Your Java Installation

Linux

1
2
3
4
5
6
7
8

# Find Java installation path
which java

# Get full path (follows symlinks)
readlink -f $(which java)

# Or use update-alternatives
update-alternatives --list java

Common locations:

• /usr/lib/jvm/java-11-openjdk-amd64
• /usr/lib/jvm/java-17-openjdk-amd64
• /usr/java/jdk-17.0.1

macOS

1
2
3
4
5
6
7
8

# Find Java home using java_home utility
/usr/libexec/java_home

# List all installed Java versions
/usr/libexec/java_home -V

# Get path for specific version
/usr/libexec/java_home -v 17

Common locations:

• /Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home
• /Applications/Android Studio.app/Contents/jbr/Contents/Home

Windows

1
2
3
4
5

# From Command Prompt
where java

# From PowerShell
(Get-Command java).Path

Common locations:

• C:\Program Files\Java\jdk-17
• C:\Program Files\OpenJDK\jdk-17.0.1
• C:\Program Files\Eclipse Adoptium\jdk-17.0.1-hotspot

Setting JAVA_HOME

Linux

Temporary (Current Session Only)

1
2

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$PATH:$JAVA_HOME/bin

Permanent (All Sessions)

Add to ~/.bashrc or ~/.zshrc:

1
2
3
4
5
6
7
8
9

# Open your shell config file
nano ~/.bashrc  # or ~/.zshrc for Zsh

# Add these lines at the end
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$PATH:$JAVA_HOME/bin

# Save and reload
source ~/.bashrc  # or source ~/.zshrc

System-wide (All Users)

Create a file in /etc/profile.d/:

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

# Create environment file
sudo nano /etc/profile.d/java.sh

# Add this content
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$PATH:$JAVA_HOME/bin

# Make it executable
sudo chmod +x /etc/profile.d/java.sh

# Reload
source /etc/profile.d/java.sh

macOS

Using Shell Configuration

Add to ~/.zshrc (default shell on modern macOS):

1
2
3
4
5
6
7
8
9

# Open Zsh config
nano ~/.zshrc

# Add these lines
export JAVA_HOME=$(/usr/libexec/java_home)
export PATH=$JAVA_HOME/bin:$PATH

# Save and reload
source ~/.zshrc

For Specific Java Version

1
2
3
4
5
6
7
8

# Java 17
export JAVA_HOME=$(/usr/libexec/java_home -v 17)

# Java 11
export JAVA_HOME=$(/usr/libexec/java_home -v 11)

# Java 1.8
export JAVA_HOME=$(/usr/libexec/java_home -v 1.8)

For Android Studio’s JDK

1
2

export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"
export PATH=$JAVA_HOME/bin:$PATH

Windows

Using System Properties (GUI)

1. Open Start Menu, search for “Environment Variables”
2. Click Edit the system environment variables
3. Click Environment Variables button
4. Under System variables, click New
5. Set:
   • Variable name: JAVA_HOME
   • Variable value: C:\Program Files\Java\jdk-17 (your Java path)
6. Click OK
7. Find Path variable, click Edit
8. Click New and add: %JAVA_HOME%\bin
9. Click OK on all dialogs
10. Restart any open Command Prompts

Using Command Prompt (Admin)

1
2

setx JAVA_HOME "C:\Program Files\Java\jdk-17" /M
setx PATH "%PATH%;%JAVA_HOME%\bin" /M

Note: /M sets system-wide. Remove it for user-only.

Using PowerShell (Admin)

1
2
3

[System.Environment]::SetEnvironmentVariable("JAVA_HOME", "C:\Program Files\Java\jdk-17", "Machine")
$path = [System.Environment]::GetEnvironmentVariable("PATH", "Machine")
[System.Environment]::SetEnvironmentVariable("PATH", "$path;%JAVA_HOME%\bin", "Machine")

Verify Installation

After setting JAVA_HOME, verify it’s working:

Linux/macOS

1
2
3
4
5
6
7
8
9
10
11

# Check JAVA_HOME value
echo $JAVA_HOME

# Verify Java is accessible
java -version

# Verify javac (compiler) is accessible
javac -version

# Full test
$JAVA_HOME/bin/java -version

Expected output:

1
2
3

openjdk version "17.0.1" 2021-10-19
OpenJDK Runtime Environment (build 17.0.1+12)
OpenJDK 64-Bit Server VM (build 17.0.1+12, mixed mode)

Windows

1
2
3
4
5
6
7
8

# Check JAVA_HOME value
echo %JAVA_HOME%

# Verify Java is accessible
java -version

# Verify javac (compiler) is accessible
javac -version

Common Issues

“JAVA_HOME is not defined”

Solution: Ensure you’ve reloaded your shell or restarted your terminal after setting the variable.

1
2
3
4

# Linux/macOS - reload config
source ~/.bashrc  # or ~/.zshrc

# Windows - restart Command Prompt/PowerShell

“command not found: java” after setting JAVA_HOME

Solution: Make sure you also added $JAVA_HOME/bin to your PATH.

1
2
3
4
5

# Check if JAVA_HOME/bin is in PATH
echo $PATH | grep "$JAVA_HOME"

# If not, add it
export PATH=$PATH:$JAVA_HOME/bin

Wrong Java version being used

Solution: Check if multiple Java installations exist and PATH order.

1
2
3
4
5
6
7
8

# Find all Java locations
which -a java

# Check PATH order
echo $PATH

# Ensure JAVA_HOME/bin appears early in PATH
export PATH=$JAVA_HOME/bin:$PATH  # Note: JAVA_HOME/bin comes FIRST

Maven/Gradle still can’t find Java

Solution: Some tools need explicit JAVA_HOME. Verify the path points to JDK, not JRE:

1
2
3
4
5

# Should show JDK directory with 'bin', 'lib', 'include', etc.
ls $JAVA_HOME

# Must contain javac (Java compiler)
ls $JAVA_HOME/bin/javac

Multiple Java Versions

If you need to switch between Java versions:

Linux - Using update-alternatives

1
2
3
4

# List available Java versions
sudo update-alternatives --config java

# Select the version you want by entering the number

macOS - Using jenv

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

# Install jenv
brew install jenv

# Add to shell config
echo 'export PATH="$HOME/.jenv/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(jenv init -)"' >> ~/.zshrc

# Add Java versions
jenv add /Library/Java/JavaVirtualMachines/jdk-11.jdk/Contents/Home
jenv add /Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home

# Set global version
jenv global 17

# Set local version (project-specific)
cd your-project
jenv local 11

Windows - Manual switching

Create batch files for each version:

java11.bat:

1
2
3

@echo off
setx JAVA_HOME "C:\Program Files\Java\jdk-11" /M
echo Java 11 is now active

java17.bat:

1
2
3

@echo off
setx JAVA_HOME "C:\Program Files\Java\jdk-17" /M
echo Java 17 is now active

Quick Reference

Linux/macOS

1
2
3
4
5
6
7
8
9
10
11

# Set JAVA_HOME temporarily
export JAVA_HOME=/path/to/java
export PATH=$JAVA_HOME/bin:$PATH

# Set JAVA_HOME permanently (add to ~/.bashrc or ~/.zshrc)
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH

# Verify
echo $JAVA_HOME
java -version

Windows (Command Prompt)

1
2
3
4
5
6
7

# Set JAVA_HOME permanently (run as Admin)
setx JAVA_HOME "C:\Program Files\Java\jdk-17" /M
setx PATH "%PATH%;%JAVA_HOME%\bin" /M

# Verify (restart CMD first)
echo %JAVA_HOME%
java -version

macOS with Android Studio JDK

1
2
3
4
5
6

# Add to ~/.zshrc
export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"
export PATH=$JAVA_HOME/bin:$PATH

# Reload
source ~/.zshrc

Additional Environment Variables

If you’re also developing Android apps, you might need:

1
2
3
4
5
6
7

# Android SDK
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools

# Or on Linux
export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools

For Node.js version management with NVM:

1
2
3
4

# Add to ~/.bashrc or ~/.zshrc
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

Conclusion

Setting JAVA_HOME correctly ensures your Java development tools work smoothly. Remember to:

• Use the JDK directory, not JRE
• Add $JAVA_HOME/bin to your PATH
• Reload your shell after making changes
• Verify with java -version and echo $JAVA_HOME

For projects requiring specific Java versions, consider using version managers like jenv (macOS/Linux) or SDKMAN! (all platforms).

What is Swap?

Swap is disk space used as virtual memory when your system’s RAM is full. When RAM usage is high, Linux moves inactive pages from RAM to swap, freeing up memory for active processes.

Why You Need Swap on Raspberry Pi

• Prevent Out-of-Memory (OOM) Errors: Protects against crashes when RAM is exhausted
• Run Memory-Intensive Applications: Allows compilation, image processing, or databases
• Improve Multitasking: System remains responsive under memory pressure
• Enable Hibernation: Required for suspend-to-disk (if configured)

Note: While swap helps, it’s much slower than RAM. Don’t rely on it for performance-critical operations.

Prerequisites

• Raspberry Pi with Raspbian/Raspberry Pi OS
• Root or sudo access
• Free disk space (recommended: 1-2GB for swap)
• SD card with wear leveling (swap causes more writes)

Step 1: Check Current Swap Status

First, verify if swap is already configured:

1

sudo swapon --show

Expected output:

• If swap exists: Shows swap file/partition details (name, size, usage)
• If no swap: No output (empty)

You can also check with:

1

free -h

Look at the “Swap” row. If it shows 0B, no swap is configured.

Step 2: Create Swap File

Create a 1GB swap file using fallocate:

1

sudo fallocate -l 1G /swapfile

Command breakdown:

• fallocate: Quickly allocates disk space
• -l 1G: Size of the swap file (1 gigabyte)
• /swapfile: Location and name of the swap file

Choosing swap size:

• 512MB RAM or less: 1-2GB swap
• 1GB RAM: 1GB swap
• 2GB RAM: 512MB-1GB swap
• 4GB+ RAM: 512MB or none

Alternative method (if fallocate doesn’t work):

1

sudo dd if=/dev/zero of=/swapfile bs=1M count=1024

This creates a 1GB file (1024 blocks × 1MB each).

Step 3: Verify File Creation

Check that the swap file was created with the correct size:

1

ls -lh /swapfile

Expected output:

1

-rw-r--r-- 1 root root 1.0G Dec 29 17:30 /swapfile

The file should be exactly 1GB.

Step 4: Set Correct Permissions

Critical security step! Swap files must be readable only by root to prevent information leaks:

1

sudo chmod 600 /swapfile

Verify the permissions changed:

1

ls -lh /swapfile

Expected output:

1

-rw------- 1 root root 1.0G Dec 29 17:30 /swapfile

Notice the permissions are now 600 (only root can read/write).

Why this matters: Swap may contain sensitive data from memory (passwords, encryption keys). Wrong permissions could expose this data to other users.

Step 5: Format as Swap

Set up the file as swap space:

1

sudo mkswap /swapfile

Expected output:

1
2

Setting up swapspace version 1, size = 1024 MiB (1073737728 bytes)
no label, UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

This formats the file with the swap signature and metadata.

Step 6: Enable Swap

Activate the swap file:

1

sudo swapon /swapfile

The swap is now active! Verify it:

1

sudo swapon --show

Expected output:

1
2

NAME      TYPE SIZE USED PRIO
/swapfile file   1G   0B   -2

Or check with:

1

free -h

You should see swap space listed under the “Swap” row.

Step 7: Make Swap Permanent

The swap file will be lost on reboot unless you add it to /etc/fstab.

Back up fstab first:

1

sudo cp /etc/fstab /etc/fstab.backup

Add the swap file to fstab:

1

echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Verify it was added:

1

tail -1 /etc/fstab

Expected output:

1

/swapfile none swap sw 0 0

Now swap will automatically activate on boot.

Step 8: Adjust Swappiness (Optional)

Swappiness controls how aggressively the kernel uses swap. Value range: 0-100.

Check current swappiness:

1

cat /proc/sys/vm/swappiness

Default: Usually 60

Recommended for Raspberry Pi:

• 10: Prefer RAM, use swap only when necessary (recommended for SD cards)
• 60: Default balanced behavior
• 100: Aggressively use swap

Set swappiness temporarily (lost on reboot):

1

sudo sysctl vm.swappiness=10

Make it permanent:

1

echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf

Why lower swappiness on Pi:

• Reduces SD card wear (fewer write cycles)
• Improves performance (RAM is much faster)
• Only uses swap when truly needed

Step 9: Adjust Cache Pressure (Optional)

Cache pressure determines how aggressively the kernel reclaims inode and dentry caches.

Check current value:

1

cat /proc/sys/vm/vfs_cache_pressure

Default: 100

Set a lower value to keep more file system cache in memory:

1

sudo sysctl vm.vfs_cache_pressure=50

Make it permanent:

1

echo 'vm.vfs_cache_pressure=50' | sudo tee -a /etc/sysctl.conf

Verification

Test that everything is working correctly:

Check Swap Status

1
2
3
4
5
6
7
8

# Show swap devices
sudo swapon --show

# Show memory and swap usage
free -h

# Show detailed memory info
cat /proc/meminfo | grep -i swap

Test Swap Under Load

Create artificial memory pressure to force swap usage:

1
2
3
4
5

# Install stress tool
sudo apt-get install stress

# Run memory stress test (use 90% of RAM)
stress --vm 1 --vm-bytes $(awk '/MemAvailable/{printf "%d\n", $2 * 0.9;}' < /proc/meminfo)k --timeout 30s

Monitor swap usage during the test:

1

watch -n 1 free -h

You should see the “Swap” usage increase.

Troubleshooting

Swap Not Activating on Boot

Check fstab entry:

1

cat /etc/fstab | grep swap

Test fstab manually:

1
2
3

sudo swapoff /swapfile
sudo swapon -a  # Activates all swap in fstab
sudo swapon --show

“fallocate: fallocate failed: Operation not supported”

Some filesystems don’t support fallocate. Use dd instead:

1

sudo dd if=/dev/zero of=/swapfile bs=1M count=1024 status=progress

Swap File Too Large for SD Card

Reduce swap size:

1
2
3
4
5
6
7
8
9

# Remove existing swap
sudo swapoff /swapfile
sudo rm /swapfile

# Create smaller swap (512MB)
sudo fallocate -l 512M /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

System Still Running Out of Memory

• Increase swap size: Follow removal steps, then create larger swap
• Reduce swappiness: Set to 10 or lower
• Close unnecessary services: Free up RAM
• Add more physical RAM: Consider upgrading Pi model

SD Card Wearing Out Quickly

Swap causes many write cycles. To reduce wear:

1. Lower swappiness to 10
2. Use USB storage for swap instead of SD card:

   1 2	sudo fallocate -l 1G /media/usb/swapfile # Follow same steps but use USB path

3. Monitor SD card health regularly

Managing Swap

Disable Swap Temporarily

1

sudo swapoff /swapfile

Re-enable Swap

1

sudo swapon /swapfile

Remove Swap Completely

1
2
3
4
5
6
7
8

# Disable swap
sudo swapoff /swapfile

# Remove fstab entry
sudo sed -i '/\/swapfile/d' /etc/fstab

# Delete swap file
sudo rm /swapfile

Resize Swap

To change swap size, you must remove and recreate it:

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

# Disable current swap
sudo swapoff /swapfile

# Remove old swap file
sudo rm /swapfile

# Create new swap with desired size (e.g., 2GB)
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Verify
sudo swapon --show

Performance Monitoring

Monitor swap usage over time:

1
2
3
4
5
6
7
8

# Real-time monitoring
watch -n 2 'free -h && echo && swapon --show'

# Check swap I/O
iostat -x 2

# View processes using swap
for file in /proc/*/status ; do awk '/VmSwap|Name/{printf $2 " " $3}END{ print ""}' $file; done | sort -k 2 -n -r | head -10

Alternative: Using zram Instead

For better performance and less SD card wear, consider zram (compressed RAM):

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

# Install zram tools
sudo apt install zram-tools

# Configure zram
echo 'ALGO=lz4' | sudo tee -a /etc/default/zramswap
echo 'PERCENT=50' | sudo tee -a /etc/default/zramswap

# Start zram
sudo systemctl start zramswap

# Enable on boot
sudo systemctl enable zramswap

Zram compresses memory in RAM itself, avoiding slow disk I/O and SD card wear.

Quick Reference

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

# Check swap status
sudo swapon --show
free -h

# Create 1GB swap
sudo fallocate -l 1G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Make permanent
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

# Optimize for SD card
sudo sysctl vm.swappiness=10
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf

# Disable swap
sudo swapoff /swapfile

# Enable swap
sudo swapon /swapfile

Step 1. Install

1
2

sudo apt update
sudo apt install asterisk

Check that asterisk started (you should see “active (running)”)

1

sudo systemctl status asterisk

Step 2. Configure accounts

In sudo nano /etc/asterisk/pjsip.conf

Add configuration:

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
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

[transport-udp]
type=transport
protocol=udp 
bind=0.0.0.0:5060 ; you can change default port
external_media_address=[ip address of VPS]
external_signaling_address=[ip address of VPS]
local_net=192.168.0.0/16 ;optional
local_net=10.0.0.0/8 ;optional

; ----- User 1 -----
[1001]
type=endpoint
context=internal
disallow=all
allow=ulaw
auth=1001
aors=1001
direct_media=no ; Force RTP through Asterisk 
rtp_symmetric=yes ; Important for NAT 
force_rport=yes ; Important for NAT 
rewrite_contact=yes ; Important for NAT

[1001]
type=auth
auth_type=userpass
password=strongpassword1
username=1001

[1001]
type=aor
max_contacts=1
remove_existing=yes

; ----- User 2 -----
[1002]
type=endpoint
context=internal
disallow=all
allow=ulaw
auth=1002
aors=1002
direct_media=no ; Force RTP through Asterisk 
rtp_symmetric=yes ; Important for NAT 
force_rport=yes ; Important for NAT 
rewrite_contact=yes ; Important for NAT
media_encryption=sdes  ; Enable SRTP for encrypted audio, which can be not supported on old devices, set no for old devices or apps. Or sdes, or dtls, or srtp

[1002]
type=auth
auth_type=userpass
password=strongpassword2
username=1002
;realm=[your domain] ; in some cases if you set defaul-realm you need to set the same for all clients

[1002]
type=aor
max_contacts=1
remove_existing=yes
qualify_frequency=60
maximum_expiration=3600
minimum_expiration=60

; Repeat if you need more users

Explanation of key parameters:

• type=endpoint - Defines the SIP endpoint
• context=internal - Which dialplan context to use
• auth=1001 - Links to the auth section
• aors=1001 - Links to the AOR (Address of Record)
• max_contacts=1 - How many devices can register simultaneously
• remove_existing=yes - Replaces old registration on new login
• direct_media=no - Forces RTP through Asterisk (useful for NAT)
• media_encryption=no - Encryption

Options media_encryption:

• no - No encryption
• sdes - SRTP with SDES key exchange
• dtls - SRTP with DTLS key exchange
  Use Optional Encryption:

1
2

media_encryption=sdes
media_encryption_optimistic=yes ; Allow fallback to unencrypted

Define Dialplan in /etc/asterisk/extensions.conf
(For example, any user can call another (e.g., 1001 → 1002).)

1
2
3
4

[internal]
exten => _1XXX,1,Dial(PJSIP/${EXTEN},20)
exten => _1XXX,n,Hangup()

Reload Asterisk

1
2
3
4
5
6

sudo asterisk -rx "reload"

# OR

sudo systemctl restart asterisk

To verify users

1
2
3

sudo asterisk -rvvv
# then:
pjsip show endpoints

RTP Media Ports (Optional)
You can reduce numbers of ports for RTP
in /etc/asterisk/rtp.conf

1
2
3

[general]
rtpstart=10000
rtpend=20000

Check logs

1

sudo asterisk -rvvv

On my old Ubuntu server, I needed additional changes for using PJSIP instead of chan_sip (the legacy SIP channel driver). Without these changes, settings from above will not work (because settings for chan_sip should be placed in /etc/asterisk/sip.conf instead).

Config of Load PJSIP Module
in /etc/asterisk/modules.conf update list of modules for loading:

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

[modules]
autoload=yes

; Disable chan_sip
noload => chan_sip.so

; Ensure PJSIP modules are loaded
load => res_pjsip.so
load => res_pjsip_session.so
load => res_pjsip_registrar.so
load => res_pjsip_outbound_registration.so
load => chan_pjsip.so

STUN

In file: /etc/asterisk/rtp.conf

add:

1
2
3
4

[general]
rtpstart=10000
rtpend=20000
stunaddr=stun.l.google.com:19302  ; For NAT traversal

Check clients:

1
2

asterisk -rx "pjsip show endpoints" 
asterisk -rx "pjsip show contacts"