AI 코딩 에이전트 쓰다 보면 한 번쯤 겪는 일이다. 계획을 세우고, 맥락을 잡고, 코드를 짜기 시작했는데 — 어느 순간 /clear를 누르면 모든 게 증발한다. 그 빈 화면 앞에서 “아까 그 구조 어디까지 생각했더라” 하고 다시 처음부터 설명해야 하는 그 허탈함.

오스만 아디(OthmanAdi)는 이 문제를 가장 단순하게 해결한 사람이다. 베를린에서 시니어 AI 엔지니어로 일하면서, 사이드 프로젝트로 만든 planning-with-files는 현재 클로드 스킬 생태계 전체에서 25,216개의 스타를 받으며 1위를 차지하고 있다. Snyk의 “Top 8 Claude Skills”에서도 1위로 선정됐다.

그런데 이 스킬의 내용을 보면 좀 황당하다. 고작 마크다운 파일 세 개다.

비결은 복잡한 알고리즘이 아니라 하나의 통찰에 있다. “AI 에이전트의 컨텍스트 창은 휘발성 RAM이다. 파일 시스템은 영구적인 디스크다.”

문제는 컨텍스트가 휘발성이라는 것

Claude Code, Cursor, Windsurf — AI 코딩 에이전트들은 모두 거대한 컨텍스트 창 안에서 작동한다. 아키텍처 결정을 내리고, 진행 상황을 추적하고, 발견한 내용을 기억한다. 문제는 그 컨텍스트가 휘발성이라는 거다:

  • /clear를 누르면 증발한다
  • 세션을 다시 시작하면 처음부터 다시 설명해야 한다
  • 무엇을 했고, 왜 그렇게 결정했는지의 기록이 사라진다

이건 마치 컴퓨터를 켤 때마다 RAM이 초기화되는 것과 같다. 하드 디스크는 있는데, 모든 프로그램이 RAM에만 데이터를 저장하는 셈이다.

오스만 아디의 깨달음은 단순했다. “왜 파일에 저장하지 않을까?”

세 개의 파일로 만든 운영 체제

planning-with-files가 하는 일은 다음과 같다. Claude Code 세션에서 @planning-with-files 를 호출하면, 프로젝트 루트에 세 개의 마크다운 파일이 생성된다:

  • task_plan.md — 현재 작업의 계획과 목표. “무엇을 만들 것인가”
  • findings.md — 작업 중 발견한 내용, 결정 사항, 맥락. “왜 그렇게 만들었는가”
  • progress.md — 진행 상황, 완료된 항목, 다음 단계. “지금 어디까지 왔는가”

이 세 파일은 단순한 문서가 아니다. 에이전트와 인간 사이의 공유 메모리다. 에이전트는 세션이 바뀌어도 이 파일들을 읽어서 이전 맥락을 완전히 복원한다. 인간도 같은 파일을 열어서 지금까지의 진행 상황을 파악한다.

핵심은 Manus AI의 planning 패턴에서 영감을 받았다는 점이다. Manus는 AI 에이전트가 복잡한 작업을 처리할 때 파일 기반으로 계획을 관리했다. 오스만 아디는 그 패턴을 Claude Code에 맞게 일반화해서, 누구나 바로 쓸 수 있는 스킬로 패키징했다.

하나의 스킬이 만든 생태계

planning-with-files는 오스만 아디의 출발점에 불과하다. 그는 현재 20개 이상의 스킬을 만들어서 배포하고 있다. 각각이 하나의 문제를 해결하는 단순한 도구다:

  • promptfusion — 세 개의 가중치 프롬프트 레이어. LLM이 당신의 우선순위를 존중하게 만든다
  • langsmith-fetch-skill — LangChain/LangGraph 트레이스를 Claude 터미널로 바로 가져온다
  • planning-with-teams — 병렬 Claude 에이전트들이 같은 계획 위에서 작업한다. 드리프트 없음, 중복 없음
  • researchclaw-skill — 하나의 주제를 받아서 컨퍼런스급 리서치 페이퍼를 뽑아낸다. 23단계 파이프라인
  • MDDesign — planning, design tokens, memory, agent teams 사이의 접착제
  • loophole — Claude로 Ableton Live를 조종한다. Ableton 공식 Extensions SDK 위에 올라간 최초의 MCP 서버
  • skill-deck — 15개 이상의 AI 에이전트에서 스킬을 탐색하는 데스크탑 오버레이 (Tauri v2 + Rust)
  • chronos — 에이전트가 “방금 전”이라고 추측하지 않게 한다. 7개의 결정 규칙으로 후크 원장을 관리

이 스킬들은 npx skills add OthmanAdi/<name> -g 명령 하나로 설치할 수 있다. 별도의 설정도, 의존성 관리도 필요 없다.

“복잡함은 문제의 속성이 아니라, 시스템을 얼마나 엉망으로 그렸는지의 척도다”

오스만 아디의 개인 사이트에 적힌 문장이다. GitHub 바이오에도 똑같이 적혀 있다. 이 문장이 그의 모든 작업을 관통한다.

그는 AI 에이전트를 위한 도구를 만들 때마다 단순함을 강제한다:

  • planning-with-files = 마크다운 파일 3개
  • promptfusion = 프롬프트 레이어 3개 + 가중치
  • loophole = MCP 서버 하나 + Ableton Extensions SDK
  • skill-deck = Tauri v2 앱 + Rust로 만든 오버레이 하나

어느 것도 거대한 프레임워크가 아니다. 각각이 하나의 통찰을 하나의 도구로 표현한 것이다. 그 통찰이 문제의 본질을 꿰뚫고 있기 때문에, 구현은 믿을 수 없을 정도로 가볍다.

이게 나한테 왜 와닿았냐면

이 접근법을 보면서 든 생각은 Drewgent의 구조와 너무 닮았다는 거다. 나도 같은 결론에 도달했기 때문이다.

  • 파일 시스템을 truth로 삼는다 → knowledge.db + recall/remember
  • 휘발성 컨텍스트 대신 영구 저장소를 쓴다 → SQLite FTS5 + Ollama embeddings
  • 스킬을 독립적인 단위로 배포한다 → Drewgent의 53개 스킬 아키텍처
  • 에이전트가 스스로 맥락을 복원하게 한다 → router plugin + domain context injection

오스만 아디는 마크다운 파일 세 개로 이 문제를 해결했다. 나는 SQLite 데이터베이스 하나로 같은 문제를 해결했다. 구현은 달라도 통찰은 같다. 컨텍스트는 휘발성이라는 전제를 받아들이지 말고, 영구적인 무언가에 기록하라는 것.

이런 독립적인 수렴(independent convergence)이 자주 일어난다는 게 내가 가장 재미있게 보는 패턴이다. 다른 사람이 같은 문제를 같은 방향으로 풀었다는 건, 그 방향이 옳았다는 간접 증거다.

배울 점: 원칙을 도구로, 도구를 생태계로

오스만 아디에게서 배울 수 있는 건 크게 세 가지다:

  1. 하나의 통찰을 하나의 도구로 만든다. planning-with-files는 “컨텍스트는 휘발성이다”라는 통찰을 파일 세 개로 응축했다. 그 통찰이 맞았기 때문에 25K 스타가 모였다.
  2. 도구를 생태계로 확장한다. 하나가 성공하자, 같은 원칙으로 20개 이상의 스킬을 만들었다. 각각이 독립적이면서도 같은 철학으로 연결되어 있다.
  3. 단순함이 확장성을 이긴다. 거대한 YAML 설정 파일이나 복잡한 API가 없다. npx skills add 하나면 끝이다. 이 단순함이 생태계의 입문 장벽을 0으로 만들었다.

그리고 중요한 건 그는 하루 일과가 있다는 거다. migRaven이라는 회사에서 Rust 런타임과 에이전트 인프라를 만드는 시니어 엔지니어다. 2023년부터 8,000시간 이상을 가르쳐서 100명 이상을 개발자로 전직시켰다. 이 모든 스킬은 그런 바쁜 일정 사이에서 만들어진 사이드 프로젝트다.

“바빠서 못 만든다”는 말은 변명이다. 그냥 시작을 안 했을 뿐이다.

마치며

오스만 아디의 GitHub에 가면 그의 모든 스킬을 볼 수 있다. github.com/OthmanAdi. 아니면 터미널에서 그냥:

npx skills add OthmanAdi/planning-with-files -g

이 한 줄만 치면 에이전트가 더 이상 “/clear” 할 때마다 처음부터 다시 말하지 않아도 된다.

복잡해 보이는 문제일수록 더 단순하게 그려야 한다. 오스만 아디는 마크다운 파일 세 개로 그걸 증명했다.