# chamnan — 저장소가 스스로를 알게 한다

<sub>[🇬🇧 English](../../README.md) · [🇨🇳 中文](README.zh-CN.md) · [🇹🇼 繁體中文](README.zh-TW.md) · [🇯🇵 日本語](README.ja.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` — 파일마다 한 줄, 코드에서 생성됩니다. 에이전트는 인덱스를 읽고 필요한 detail만 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>