# chamnan — чтобы репозиторий знал сам себя

<sub>[🇬🇧 English](../../README.md) · [🇨🇳 中文](README.zh-CN.md) · [🇹🇼 繁體中文](README.zh-TW.md) · [🇯🇵 日本語](README.ja.md) · [🇰🇷 한국어](README.ko.md) · [🇹🇭 ไทย](README.th.md) · [🇻🇳 Tiếng Việt](README.vi.md) · [🇮🇩 Indonesia](README.id.md) · [🇮🇳 हिन्दी](README.hi.md) · [🇧🇩 বাংলা](README.bn.md) · [🇵🇰 اردو](README.ur.md) · [🇸🇦 العربية](README.ar.md) · [🇮🇱 עברית](README.he.md) · [🇹🇷 Türkçe](README.tr.md) · [🇺🇦 Українська](README.uk.md) · [🇵🇱 Polski](README.pl.md) · [🇨🇿 Čeština](README.cs.md) · [🇩🇪 Deutsch](README.de.md) · [🇳🇱 Nederlands](README.nl.md) · [🇫🇷 Français](README.fr.md) · [🇪🇸 Español](README.es.md) · [🇵🇹 Português](README.pt-PT.md) · [🇧🇷 Português (BR)](README.pt-BR.md) · [🇮🇹 Italiano](README.it.md) · [🇷🇴 Română](README.ro.md) · [🇬🇷 Ελληνικά](README.el.md) · [🇭🇺 Magyar](README.hu.md) · [🇸🇪 Svenska](README.sv.md) · [🇫🇮 Suomi](README.fi.md) · [🇩🇰 Dansk](README.da.md) · [🇳🇴 Norsk](README.no.md) · [🇵🇭 Tagalog](README.tl.md)</sub>

> На этой странице намеренно нет ни одной цифры. Все измерения — в англоязычном README, и они меняются с каждым выпуском; эта страница не меняется. → [Evidence](../../README.md#evidence)

## Что это

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

Всё, что он пишет, — обычный markdown, закоммиченный рядом с кодом. Ни сетевых вызовов во время работы, ни базы данных, ни демона, ни embedding-модели — только стандартная библиотека Python.

## Что он решает

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

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

## Установка

```bash
claude plugin marketplace add ArcticFox2029/chamnan
claude plugin install chamnan@chamnan
```

Откройте новую сессию и выполните `/chamnan:bootstrap` один раз для каждого репозитория.

<!-- generated: build_sections.py -->

## Все возможности

Четыре способности. Всё, что перечислено ниже, действительно работает в текущем выпуске. Каждую часть можно отключить отдельно в `.chamnan/config.json`, и ни одна не зависит от другой.

### Понимать — что есть и что с чем связано

| | |
|---|---|
| **Индекс** | `MAP.md` — по строке на файл, порождается из самого кода. Агент читает индекс и делает grep по нужной детали, вместо того чтобы обходить всё дерево. |
| **Влияние** | Кто зависит от этого файла и какие тесты его покрывают. Собственные импорты файла и так написаны у него сверху; дорого искать обратное ребро — сделайте grep по пути перед правкой. |
| **Модель данных** | Имена таблиц и моделей с однострочным пояснением, взятые из DDL, миграций и ORM‑моделей, а не дамп всей схемы. Появляется, только если репозиторий её действительно определяет. |
| **Поверхность API** | Метод, путь и обработчик — из декораторов маршрутов, документов OpenAPI и описаний сервисов `.proto`, а не вся спецификация. |
| **Конфигурация** | Имена переменных окружения, которые читает репозиторий. **Только имена, значения не записываются никогда** — и предупреждает, если `.env` не в gitignore. |
| **Развёртывание** | Что действительно работает: типы и имена, образы, роли, конвейеры — прочитанные из манифестов Kubernetes, Ansible, Compose, Helm и CI. От Secret берётся только имя и ничего из его содержимого. |
| **Неисходные материалы** | Сканы, выгрузки, архивы — только количество, размер и преобладающие расширения. Раздел существует, чтобы агент не пошёл смотреть сам, что обходится куда дороже. **Никогда не открывается и не читается.** |

### Помнить — что делалось и зачем

| | |
|---|---|
| **Состояние работы** | `STATE.md` — то, над чем работа идёт прямо сейчас; вставляется в начале сессии, чтобы сжатие контекста перестало это стирать. |
| **Запись сессии** | По одной записи на сессию в `.chamnan/sessions/`. В следующую сессию попадает **только незавершённое**; сессия, закрытая чисто, не вставляет ничего. |
| **Память** | `decisions/`, `lessons/`, `rules/`. Правила — постоянные ограничения, поэтому они перед агентом каждую сессию; решения и уроки дают только заголовок и читаются, когда заголовок выглядит уместным. |
| **Открытые нити** | Линии работы, которые ещё не закрыты, вместе с историей файлов, которых эта линия касалась, — и они продолжают отслеживаться после переименования файла. |

### Использовать снова — то, что уже решено

| | |
|---|---|
| **Процедуры** | Навыки, которые агент пишет **сам**, столкнувшись со сложным или повторяющимся. Это не приложенная готовая библиотека, а механизм. |
| **Инструменты** | Замечает, что тот же черновой скрипт написан снова, и предлагает его сохранить — а затем напоминает о нём прежде, чем вы напишете новый. |
| **Последовательности** | Замечает, что одни и те же команды шли в одном порядке в разные дни, и предлагает записать эту последовательность. |

### Накапливать — что репозиторий узнал о себе

| | |
|---|---|
| **Вехи** | Те немногие изменения, что переменили форму репозитория: что переехало, почему это стоило сделать, каких областей коснулось. |
| **Кандидаты** | Обнаруженные повторяющиеся последовательности команд **всегда ждут подтверждения человеком**. Ничто не повышается автоматически. |
| **Среды** | Объявите, что такое production или staging и что там запрещено, — а он предупредит, когда это объявление устареет. |
| **Отчёт** | Что лежит в рабочем пространстве, действительно ли оно достижимо, и как изменился контекст на ход в вашем репозитории. Это ваша цифра, не наша. |

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

## Команды

Все вызываются из оболочки, и агент вызывает их сам.

| | |
|---|---|
| `chamnan-map` | строит и обновляет индекс |
| `chamnan-report` | что лежит в рабочем пространстве и как изменился контекст на ход |
| `chamnan-impact` | кто зависит от этого файла и какие тесты его покрывают |
| `chamnan-timeline` | что уже происходило с этим файлом |
| `chamnan-peek` | говорит, что внутри большого файла, не читая его в контекст |
| `chamnan-promote` | сохраняет скрипт как постоянный инструмент репозитория |
| `chamnan-candidates` | посмотреть, подтвердить или отклонить обнаруженные повторы |
| `chamnan-env` | объявить среду и её запреты и проверить, свежо ли объявление |
| `chamnan-age` | где накопленное знание начало устаревать |

И навыки, вызываемые изнутри сессии: `/chamnan:bootstrap` `/chamnan:remap` `/chamnan:resume` `/chamnan:remember` `/chamnan:milestone` `/chamnan:capture` `/chamnan:promote` `/chamnan:report`

## Что он пишет и куда

Всё внутри `.chamnan/`, обычные markdown и JSON. Читается, правится вручную и удаляется в любой момент, ничего не ломая.

| | |
|---|---|
| `MAP.md` | что есть и что от чего зависит |
| `STATE.md` | что делается прямо сейчас |
| `sessions/` | где остановилась прошлая работа |
| `memory/` | решения, уроки и постоянные правила |
| `threads/` | линии работы, которые ещё открыты |
| `skills/` · `tools/` | процедуры и скрипты, которые стоит сохранить |
| `milestones.md` | изменения, переменившие форму репозитория |
| `config.json` | включение и выключение каждой части и предел размера блока, вставляемого в сессию |

**Единственная запись вне `.chamnan/`** — необязательный Git‑хук pre-commit, который держит индекс в согласии с деревом; ставится, только если вы согласились, и снимается.

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

## Безопасность

| | |
|---|---|
| **Никаких сетевых вызовов во время работы** | Ни одного. Ключ API не нужен, ничто никуда не отправляется. |
| **Не переписывает ваш исходник** | Он сообщает, а не правит. Индекс копирует комментарии, которые вы уже написали, и не сочиняет их; файлы без комментария названы поимённо, чтобы вы дописали сами. |
| **Ни демона, ни фоновой работы** | Нет постоянного процесса, нет базы данных, нет модели эмбеддингов — только стандартная библиотека Python. |
| **Секреты отфильтровываются первыми** | Всё, что будет записано или вставлено в сессию, сначала проходит фильтр секретов: *имена* переменных остаются, значения — нет. А предел, до которого этот фильтр не дотягивается, написан рядом с его же цифрой в английском README. |
| **Что установленный плагин может сделать с вами** | Полностью описано в английском README, включая то, где chamnan разрывает цепочку утечки. |

## Требования

Claude Code · Python · Git · macOS, Linux или Windows

Больше ничего, и никаких зависимостей ставить не нужно. Минимальная версия Python указана в [README › Requirements](../../README.md#requirements) — на этой странице цифр нет, потому что меняются именно цифры.

## Выключить или удалить

Отключайте по частям в `.chamnan/config.json` · остановите в одном репозитории · снимите плагин со всей машины · удалите `.chamnan/` когда угодно, ничего не сломается — подробные шаги в [README › Update, disable, uninstall](../../README.md#update-disable-uninstall)

<!-- /generated -->

## Прочтите перед установкой

**chamnan рассчитан на одну основную папку, к которой вы возвращаетесь снова и снова.** Всё, что он делает, оплачивается вперёд и возвращается в последующих сессиях — в репозитории, который вы открыли один раз, вы заплатили полностью и не получили ничего.

**Он сообщает, а не переписывает ваш код.** Индекс переносит комментарии, которые вы уже написали, и ничего не выдумывает. Файлы без комментария называются поимённо, чтобы вы дописали их сами.

**Его ограничения измерены и записаны**, включая измерения, которые говорят против его же основной возможности.

## Где подробности

| | |
|---|---|
| Каждое число и как оно измерено | [README › Evidence](../../README.md#evidence) |
| Набор регрессионных тестов — можно запустить самому | [`tests/run_tests.py`](../../tests/run_tests.py) |
| Что изменилось в каждом выпуске и почему | [CHANGELOG.md](../../CHANGELOG.md) |
| Всё остальное | [README.md](../../README.md) |

---

<sub>MIT · [github.com/ArcticFox2029/chamnan](https://github.com/ArcticFox2029/chamnan)</sub>