llm-wiki

llm-wiki

Claude Code와 Codex에서 함께 사용할 수 있는 repo-local LLM 메모리 플러그인입니다.

llm-wiki는 각 프로젝트 안에 작은 Markdown 위키를 만들고, 에이전트가 의미 있는 작업을 시작하기 전에 현재 상태를 읽고 작업이 끝난 뒤 결정/발견/로그를 한국어로 남기게 합니다. 위키가 프로젝트 안에 있기 때문에 Claude, Codex, Cursor, GPT, 사람 모두가 같은 컨텍스트를 공유할 수 있습니다.

이 구조는 Andrej Karpathy의 LLM wiki gist에서 영감을 받았고, 실제 코딩 에이전트 작업에 맞게 파일 역할과 작업 전후 절차를 정리한 형태입니다.

무엇을 만들까

llm-wiki/
  AGENTS.md          # 모든 LLM 에이전트가 따를 공통 작업 규칙
  current-state.md   # 현재 상태, 목표, 블로커, 다음 작업
  index.md           # 위키 목차와 source map
  log.md             # append-only 작업 로그
  decisions/         # ADR 스타일의 장기 결정 기록
  findings/          # 환경 이슈, 도구 제약, 검증된 발견사항
  wiki/              # 주제별 장기 지식 문서

플러그인은 공통이고, 프로젝트별 최적화는 생성된 llm-wiki/AGENTS.md, current-state.md, index.md 안에 기록합니다.

에이전트 작업 흐름

의미 있는 프로젝트 작업 전에는 에이전트가 다음 파일을 읽습니다.

1. llm-wiki/AGENTS.md
2. llm-wiki/current-state.md
3. llm-wiki/index.md
4. 현재 작업과 관련된 wiki/, decisions/, findings/ 문서만 선택적으로 읽기

의미 있는 작업 후에는 필요한 항목만 갱신합니다.

• log.md에 작업 로그 추가
• 상태가 바뀌었으면 current-state.md 갱신
• 장기 결정이 생겼으면 decisions/에 기록
• 운영/환경/도구 관련 발견이 있으면 findings/에 기록
• 재사용 가능한 주제 지식은 wiki/에 기록
• 새 파일을 만들었으면 같은 turn에서 index.md에 링크와 필요한 작업별 라우팅 추가
• 가능하면 scripts/check_index.sh llm-wiki로 durable 문서가 index에 모두 연결됐는지 확인

단순 Q&A, 짧은 포맷 변경, 일회성 유틸 작업은 위키에 기록하지 않아도 됩니다.

플러그인 구성

.claude-plugin/plugin.json   # Claude/Cowork 플러그인 manifest
.codex-plugin/plugin.json    # Codex 플러그인 manifest
commands/                    # Claude slash command
skills/llm-wiki/SKILL.md     # Claude/Codex가 공유하는 스킬 본문
skills/llm-wiki/templates/   # llm-wiki와 루트 AGENTS/CLAUDE 초기화 템플릿
skills/llm-wiki/scripts/     # 보조 스크립트
skills/llm-wiki/references/  # 필요할 때만 읽는 참고 문서

인덱스 라우팅과 검증

index.md는 단순 목차가 아니라 작업별 라우터로 관리합니다.

## 작업별 라우팅

- auth/session: [wiki/architecture.md](wiki/architecture.md), [findings/YYYY-MM-DD-auth-session.md](findings/YYYY-MM-DD-auth-session.md)
- streaming/SSE: [wiki/api-streaming.md](wiki/api-streaming.md), [findings/YYYY-MM-DD-streaming-gotcha.md](findings/YYYY-MM-DD-streaming-gotcha.md)

작업 시작 시에는 current-state.md와 index.md를 본 뒤, 라우팅에 걸린 Top 1-3개 문서만 먼저 읽습니다. 새 wiki/, decisions/, findings/ 파일을 만들면 반드시 같은 turn에서 index.md에 링크를 추가하고, 가능하면 아래 검사를 실행합니다.

bash /path/to/llm-wiki-skill/skills/llm-wiki/scripts/check_index.sh llm-wiki

설치

Claude Code와 Codex는 설치 방식이 다릅니다. Claude는 GitHub plugin 설치 흐름을 우선 사용하고, Codex는 공개 marketplace 등록 전까지 local marketplace에 등록해서 사용합니다.

Claude Code

Claude Code가 GitHub plugin add를 지원하는 환경에서는 다음 명령을 사용합니다.

claude plugin add atototo/llm-wiki-skill

Claude 내부 slash command를 쓰는 환경이라면 marketplace를 등록한 뒤 설치합니다.

/plugin marketplace add atototo/llm-wiki-skill
/plugin install llm-wiki-skill@llm-wiki-skill

환경에 따라 GitHub URL 직접 설치가 필요할 수 있습니다.

claude plugin add https://github.com/atototo/llm-wiki-skill

Codex

Codex에서 공개 plugin marketplace에 올리기 전에는 local marketplace 방식으로 등록합니다.

Codex local plugin은 다음 세 가지가 모두 맞아야 합니다.

1. 플러그인 repo가 로컬 경로에 있어야 합니다.
2. ~/.agents/plugins/marketplace.json에 등록되어야 합니다.
3. ~/.codex/config.toml에 enabled plugin으로 추가되어야 합니다.

또한 Codex discovery가 안정적으로 동작하려면 아래 이름이 일치해야 합니다.

local folder name == marketplace name == .codex-plugin/plugin.json name

이 플러그인은 모두 llm-wiki-skill을 사용합니다. UI 표시명은 LLM Wiki입니다.

1. Repo clone

원하는 로컬 경로에 repo를 둡니다. 경로는 자유지만, 예시는 ~/plugins/llm-wiki-skill을 사용합니다.

mkdir -p ~/plugins
git clone https://github.com/atototo/llm-wiki-skill.git ~/plugins/llm-wiki-skill

2. Local marketplace 등록

~/.agents/plugins/marketplace.json의 plugins 배열에 다음 entry를 추가합니다.

{
  "name": "llm-wiki-skill",
  "source": {
    "source": "local",
    "path": "./plugins/llm-wiki-skill"
  },
  "policy": {
    "installation": "INSTALLED_BY_DEFAULT",
    "authentication": "ON_USE"
  },
  "category": "Productivity"
}

path는 local marketplace source 기준 경로입니다. 일반적으로 ~/.codex/config.toml의 [marketplaces.local] source가 /Users/<user>이면 ~/plugins/llm-wiki-skill은 ./plugins/llm-wiki-skill로 등록합니다.

3. Codex config 활성화

~/.codex/config.toml에 다음 entry를 추가합니다.

[plugins."llm-wiki-skill@local"]
enabled = true

[marketplaces.local]도 있어야 합니다. 보통 다음 형태입니다.

[marketplaces.local]
source_type = "local"
source = "/Users/<user>"

4. 재시작과 확인

Codex를 완전히 종료 후 다시 시작합니다. 정상 반영되면 cache가 생성됩니다.

~/.codex/plugins/cache/local/llm-wiki-skill/0.1.0/

Plugins 화면에서는 LLM Wiki로 보일 수 있습니다. 검색창에서 LLM 또는 Wiki로 확인합니다.

프로젝트에 위키 초기화하기

프로젝트 루트에서 실행합니다.

bash /path/to/llm-wiki-skill/skills/llm-wiki/scripts/init_wiki.sh llm-wiki

초기화 스크립트는 llm-wiki/뿐 아니라 루트 AGENTS.md, CLAUDE.md 진입점도 자동으로 생성합니다. 기존 루트 파일이 이미 있으면 덮어쓰지 않고, llm-wiki 진입점 문구를 수동 병합하도록 안내합니다.

그다음 바로 프로젝트에 맞게 수정합니다.