# chamnan — リポジトリに自分自身を把握させる

<sub>[🇬🇧 English](../../README.md) · [🇨🇳 中文](README.zh-CN.md) · [🇹🇼 繁體中文](README.zh-TW.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) · [🇺🇦 Українська](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 のプラグインです。ファイルを一つずつ走査する代わりに agent が読むためのインデックスをリポジトリに作り、作業のなかで積み上がった技術的な文脈——作業状態、セッションの記録、判断の理由、毎回導き直している手順——を残します。

書き出されるものはすべて、コードの隣にコミットされる普通の markdown です。実行時にネットワークを呼ばず、データベースもデーモンも embedding モデルもありません。Python の標準ライブラリだけで動きます。

## 何を解決するのか

セッションが新しくなるたび、あるいはコンテキストが圧縮されるたびに、agent がそのコードベースについて理解していたことは失われ、また grep からやり直しになります。

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 する。ツリーを歩き回る必要がなくなります。 |
| **影響範囲** | そのファイルに依存しているのは誰か、どのテストが覆っているか。自分の import はファイル冒頭に書いてあり、毎回探す羽目になるのは逆方向の辺のほうです —— 変更前にパスで 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 › 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>