brain-protocol

Brain Protocol — Full Methodology (v3.0)

Обезличенный реюзабельный протокол памяти и непрерывности. Проектная специфика живёт в .claude/brain.conf и в project CLAUDE.md, а не здесь.

Configuration

Прочитать .claude/brain.conf в корне проекта:

vault_name=ProjectName
vault_base=~/Documents/Obsidian Vault   # опционально

Вывести пути:

VAULT = <vault_base>/<vault_name>
STATE = $VAULT/4. Активная работа/SESSION_STATE.md   # ОДИН канонический файл

Vault Map (6 папок)

Папка	Что внутри	Когда читать
1. Проект/	Обзор, стек, архитектура	новый контекст, архитектурные задачи
2. Модули/	По файлу на модуль (YAML-свойства)	ОБЯЗАТЕЛЬНО перед правкой модуля
3. Журнал/ГГГГ-ММ/	История ВСЕХ изменений	ОБЯЗАТЕЛЬНО перед правкой модуля
4. Активная работа/	SESSION_STATE.md, _state_backups/	ПЕРВЫМ ДЕЛОМ каждую сессию
5. Планы/	Роадмап, баги, тех-долг, идеи	планирование, рефакторинг, крупное
6. Справочник/	Дизайн-система, паттерны, шаблоны записей	новый код, PR, записи в vault

YAML-свойства (у каждого файла vault)

---
title: ...
type: module | changelog | audit | reference | roadmap | project
status: active | done | draft | archived
created: YYYY-MM-DD
updated: YYYY-MM-DD
related: ["[[…]]"]
owner: Author
---

SESSION_STATE.md — формат (v3.0)

Лёгкий нарратив + машинные якоря (frontmatter + одна строка → Следующий шаг:), которые читают хуки.

---
last_updated: ГГГГ-ММ-ДД ЧЧ:ММ
task_id: "short-id"
compression_count: 0
session_label: ""
---
# SESSION_STATE — <Project>
## Сейчас
[над чем работаем прямо сейчас, фаза]
→ Следующий шаг: [файл + КОНКРЕТНОЕ действие. «продолжить работу» = невалидно]
## Очередь
- [ ] однострочные задачи
## Решения (свежие)
- [решение] — [почему] (детали в 3. Журнал/)
## Заметки / контекст
[свободно: креды, ссылки на журналы/планы, флаги ревью]

Канонический якорь — ровно одна строка → Следующий шаг: (по ней хуки восстанавливают точку возобновления). Не дублировать → в нарративе.

🧭 Routing Matrix — когда что читать и писать

Ядро протокола. Подробно с примерами — references/routing-matrix.md.

Триггер	ЧИТАТЬ до	ПИСАТЬ после
Старт сессии / «продолжай»	4.(STATE); новый контекст — 1. Проект	—
Перед правкой модуля	2. Модули/<m> + свежее 3. Журнал	—
Реализация фичи / нового кода	grep кода + 2. Модули + 5. Планы	—
Завершён юнит работы	—	3. Журнал/ГГГГ-ММ (+ 2. Модули если модуль изменился, + 5. Планы если сдвинулся объём)
Новый модуль / подсистема	1. Проект + 6. Справочник	новый файл 2. Модули + паттерны 6. Справочник
Принято решение/трейдофф	—	STATE → «Решения» + 3. Журнал
Каждый шаг / ~5 сообщений	—	STATE (якоря)
Сдвиг плана/объёма	5. Планы	5. Планы + флаг ревью

Запреты: ❌ второй SESSION_STATE не создавать (он один; при реорганизации vault — mv, не copy). ❌ STATE не раздувать (завершённое → в журнал). ❌ не лезть в vault чужого проекта. ❌ готовые файлы — точечные правки, без широких регенеративных проходов.

Work Protocol

STEP 0 → Прочитать STATE. Незавершённая задача? Уточнить у пользователя.
STEP 1 → Определить модули. По матрице прочитать 3. Журнал + 2. Модули. Крупное: + 6. Справочник + 1. Проект.
STEP 1.5 → grep по кодовой базе перед написанием нового кода.
STEP 2 → План в STATE: «Сейчас» + одна строка «→ Следующий шаг:», остальное — «Очередь».
STEP 3 → Выполнять. Перед шагом — обновить «→ Следующий шаг:». После — двигать дальше.
STEP 4 → Завершено → запись в 3. Журнал/. Обновить 2. Модули / 5. Планы / 6. Справочник по матрице.
STEP 5 → Ротация STATE: завершённое в журнал, следующее из очереди → «Сейчас».

Read/Write Rules

ПИСАТЬ в STATE — перед и после значимого шага, при правке файла, при решении, при уточнении от пользователя, принудительно каждые ~5 сообщений.

ЧИТАТЬ STATE — первое сообщение сессии, на «продолжай/дальше», когда контекст ощущается неполным, перед продолжением многошаговой задачи.

Recovery After Compaction

A: Прочитать STATE
B: Прочитать свежий файл из 3. Журнал/[текущий месяц]/
C: Прочитать WIP из 4. Активная работа/
D: Найти строку «→ Следующий шаг:» → выполнять ИМЕННО его

compression_count инкрементирует pre-compact хук автоматически (в Desktop без хуков — вручную).

ЗАПРЕЩЕНО после восстановления: спрашивать «на чём остановились», пересказывать сделанное, менять план, пропускать шаги. ОБЯЗАТЕЛЬНО: продолжить со строки → Следующий шаг:, первое сообщение = «Далее — [действие]».

Parallel-Session Safety

• SESSION_STATE — один канонический файл. Дубль не создавать никогда.
• На старте сессии хук проверяет свежесть last_updated: если STATE обновлён ≤10 мин назад — предупреждение о возможной параллельной сессии. Не затирать STATE вслепую; при сомнении уточнить у пользователя.
• session_label в frontmatter — необязательная человекочитаемая метка сессии-владельца.
• Если vault реорганизовали и STATE «раздвоился» — файл переносить (mv), старую копию архивировать в _state_backups/, не плодить.

Generic Workflow (оркестрация)

Применять, если проект работает через оркестратор + специализированных субагентов:

• Оркестратор держит STATE/git/секреты; доменную работу делегирует профильным агентам.
• Крупные задачи — фазами/эпиками; план фаз — в 5. Планы/.
• После рабочего агента — ревью-гейт (review/QA), затем фиксация в журнале.
• Узкий скоуп: готовые/«хорошие» файлы правят точечно (Edit), без широких «redesign/cleanup» проходов, иначе теряются прежние правки.

Token Economy

• grep-before-implement — никогда не писать новый код без поиска существующего (≈100 токенов vs ~70K на дубль).
• --quiet, | tail -n 20 для build/test; grep -n → читать только нужный диапазон; не выводить файлы целиком.
• После сжатия — перед любым Edit перечитать «Заметки/контекст» в STATE: что уже найдено/проверено.

Additional Resources

• references/routing-matrix.md — расширенная матрица «когда что читать/писать» с примерами.
• references/templates.md — шаблоны записей для 3. Журнал/, 5. Планы/, 2. Модули/.
• references/project-rules.md — пустой шаблон критичных правил под конкретный проект (живёт в project CLAUDE.md).