# 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.ru.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>