Claude Code를 위한 OKF: 에이전트(및 팀)가 읽을 수 있는 구조화되고 이식 가능한 메모리

문제점: 에이전트는 매 세션마다 당신의 프로젝트를 잊어버립니다

코딩 에이전트와 협업해 보았다면 이런 경험을 해보셨을 것입니다: 새로운 세션이 시작되면 컨텍스트(Context)가 사라집니다. 에이전트는 당신의 인증 흐름(auth flow)을 다시 발견하고, 왜 그런 결정이 내려졌는지 다시 추측하며, 어제 이미 설명했던 정신적 모델(mental model)을 재구축하기 위해 동일한 파일들을 다시 읽습니다. 프로젝트 지식 — 시스템 뒤에 숨겨진 '이유(why)', 런북(runbooks), "이것은 건드리지 마세요, 이유는 이렇습니다"와 같은 정보들 — 은 위키(wiki), 코드 주석, 그리고 사람들의 머릿속에 흩어져 있습니다. 이 중 그 어떤 것도 코드와 함께 이동하지 않으며, 새로운 컨텍스트 창(context window)에서도 살아남지 못합니다.

CLAUDE.md가 도움이 되긴 하지만, 이는 '고정된 지침(standing instructions)'을 위한 것이며 모든 프롬프트에 통째로 로드됩니다. 자동 메모리(Auto-memory)는 에이전트가 습득한 내용을 포착하지만, 이는 암시적(implicit)이고 에이전트별로 다르며 검토 과정을 거치지 않습니다. 위키는 인간을 위한 것이며 별도의 내보내기(exporting)가 필요합니다. 여기에 간극이 존재합니다: 구조화되어 있고, 코드와 함께 버전 관리되며, 어떤 에이전트나 사람도 읽을 수 있는 큐레이션된 팀 지식이 필요합니다.

OKF란 무엇인가

Open Knowledge Format (OKF)는 지식을 YAML 프론트매터(frontmatter)가 포함된 마크다운(markdown) 파일 디렉토리로 표현하는 개방형, 벤더 중립적 형식(2026년 6월 Google Cloud Data Cloud 팀이 발표, Apache-2.0)입니다. 이것이 핵심 아이디어입니다. 스키마 레지스트리(schema registry), 런타임(runtime), SDK도 필요 없습니다. 파일을 cat 할 수 있다면 읽을 수 있고, 저장소(repo)를 git clone 할 수 있다면 배포할 수 있습니다.

번들은 다음과 같은 형태를 가집니다:

.okf/
├── index.md                  # 점진적 공개 (root에 okf_version 포함)
├── log.md                    # ISO 날짜 기반 변경 이력, 최신순
...

각 개념이 규격을 준수하기 위해 필요한 것은 단 하나입니다: 비어 있지 않은 type을 포함한 YAML 프론트매터(YAML frontmatter)입니다. 그 외의 모든 것은 선택 사항입니다.

---
type: Service
title: "Auth API"
...

개념(Concepts)들은 일반적인 마크다운 링크(markdown links)로 서로 연결되며, 이를 통해 번들(bundle)은 타입이 지정되고 상호 참조된 지식의 그래프(graph)가 됩니다. 이는 텍스트일 뿐이기에 차이점 비교(diffable)가 가능하고, PR(Pull Request)에서 검토할 수 있으며, 다양한 도구 간에 이식(portable)이 가능합니다.

okf-skills가 추가하는 기능

OKF는 포맷(format)입니다. **okf-skills**는 v0.1 명세(spec)를 그대로 따라 에이전트가 이를 실제로 사용할 수 있도록 교육하는 Claude Code 네이티브 툴체인(toolchain)입니다. 이는 Claude Code 플러그인 및 에이전트 스킬(agent skills) 형태로 제공됩니다(Cursor, Codex 및 skills.sh를 통해 20개 이상의 에이전트에 설치 가능). 세 가지 구성 요소는 다음과 같습니다:

검증기(validator)와 시각화 도구(visualizer) 또한 독립적인 스크립트(uv run, PEP 723을 통한 PyYAML 사용)이므로, 플러그인으로 설치하든 스킬로 설치하든 동일하게 작동합니다. 시각화 도구의 출력물은 단일 viz.html 파일입니다. 개념은 노드(nodes)로, 링크는 엣지(edges)로 표현되며, 렌더링된 마크다운과 "Links to / Cited by" 백링크(backlinks)가 포함된 위키(wiki) 스타일의 상세 패널을 제공합니다. 백엔드(backend)는 없으며, 페이지 외부로 나가는 데이터도 없습니다. 실제 번들을 확인할 수 있는 라이브 데모가 있으며, 해당 저장소는 OKF로 자체 문서화되어 있고, CI(지속적 통합)를 통해 매 푸시(push)마다 해당 번들을 검증합니다.

솔직한 범위

솔직하게 밝혀둘 몇 가지 사항이 있습니다:

• OKF는 큐레이션이지 마법이 아닙니다. 이는 지식을 자동으로 캡처하는 시스템이 아니라, 의도적으로 지식을 배치하는 장소입니다. 누군가(사용자 또는 요청에 따른 에이전트)가 여전히 개념을 작성해야 합니다. 보상은 노력이 전혀 들지 않는 것이 아니라, 지속성(durability)과 이식성(portability)입니다.
• 대체재가 아닌 보완재입니다. _어떻게 행동할지(how to behave)_는 CLAUDE.md를, _에이전트가 무엇을 습득했는지(what the agent picked up)_는 자동 메모리(auto-memory)를, _팀이 무엇을 알고 있는지(what the team knows)_는 OKF 번들(bundle)을 사용하세요. 이들은 서로 쌓여 시너지를 냅니다.
• 설계상 훅(hooks)이 없습니다. 플러그인이 사용자의 리포지토리(repo)를 조용히 재작성하지 않습니다. 자동 유지 관리(automatic upkeep)는 선택 사항입니다(아래 참조).
• 포맷 사양은 Google의 것이며, 출처를 밝히고 그대로 가져왔습니다. 이 플러그인의 자체 코드는 MIT © Marco Boffo 라이선스를 따릅니다.

설치 및 사용해보기

Claude Code 플러그인으로 사용 시:

/plugin marketplace add scaccogatto/okf-skills
/plugin install okf@scaccogatto

에이전트 스킬(Agent skills)로 사용 시 (Claude Code, Cursor, Codex, 20개 이상의 에이전트):

npx skills add scaccogatto/okf-skills

그 다음 캡처, 검증 및 시각화를 수행하세요:

/okf:okf produce .okf          # 또는 단순히 요청: "auth service를 OKF로 문서화해줘"
/okf:validate .okf --strict
/okf:visualize .okf            # 공유 가능한 viz.html을 엽니다

모든 개념에는 딥 링크(deep link)가 부여됩니다. 예를 들어 viz.html#services/auth-api는 해당 개념이 이미 선택된 상태로 그래프를 로드합니다.

자동 유지 관리(작업 전 .okf/를 참조하고, 변경 후 지식을 다시 기록하는 기능)를 켜려면, templates/CLAUDE-okf.md를 프로젝트의 CLAUDE.md에 붙여넣으세요. 이는 소프트 모드이며 전적으로 선택 사항(opt-in)입니다. 스크립트 실행을 위해 uv (또는 python3 + pyyaml)가 필요합니다.

왜 해야 하는가

제안하는 핵심은 작고 구체적입니다: 매일 아침 새로운 에이전트에게 지식을 다시 설명하는 대신, 프로젝트의 지식에 설명 대상인 코드와 함께 버전 관리되는, 하나의 지속 가능하고, 차이점 확인(diffable)이 가능하며, 이식 가능한 홈을 제공하는 것입니다. 단순한 마크다운(markdown) 형식이므로, 최악의 경우에도 팀이 읽을 수 있는 좋은 문서를 작성하게 되는 셈입니다. 최선의 경우, 에이전트가 더 이상 망각하지 않게 됩니다.

Repo, 데모 및 스펙: github.com/scaccogatto/okf-skills. 이슈(Issues) 및 PR(Pull Requests)을 환영합니다.