Molayo

© 2026 Molayo

Dev.to헤드라인2026. 06. 23. 22:00

AI 코딩 에이전트가 매 세션마다 모든 것을 잊어버린다면? Markdown과 YAML로 해결했습니다.

요약

코딩 에이전트가 매 세션마다 컨텍스트를 잃어버리는 문제를 Markdown과 YAML 파일을 활용해 해결하는 방법을 소개합니다. Git 리포지토리 내에 지속 가능한 상태 정보를 저장함으로써 모델에 구애받지 않는 안정적인 컨텍스트 유지가 가능합니다.

핵심 포인트

  • 에이전트의 컨텍스트 유지를 위해 채팅 외부의 파일(Markdown, YAML) 활용
  • Git 리포지토리를 활용하여 데이터베이스나 SaaS 없이도 지속성 확보
  • 모델 및 도구에 구애받지 않는(Agnostic) 범용적인 컨텍스트 관리
  • 파일 기반 저장 방식을 통한 투명한 감사(Audit) 및 관리 가능

코딩 에이전트와 새로운 세션을 시작할 때마다, 에이전트는 항상 제로 상태에서 시작했습니다. 제가 어떤 리포지토리(repos)들을 가로질러 작업하고 있는지? 이 작업은 어떤 클라이언트를 위한 것인지? 어제 어디까지 진행했는지? 저는 매번 같은 컨텍스트(context)를 다시 설명해야 했고, 에이전트는 가끔 잘못된 프로젝트를 불러왔으며, 지난주에 결정한 그 어떤 것도 이번 세션까지 이어지지 않았습니다. 매 세션마다 발생하는 "자기 자신을 다시 설명해야 하는" 세금과 같았습니다.

처음에는 뻔한 해결책을 시도해 보았습니다. 더 나은 프롬프트(prompt), 더 긴 시스템 메시지(system message)를 사용하는 것이었죠. 하지만 효과가 없었습니다. 지속되어야 하는 컨텍스트는 채팅 내부에 머물 수 없습니다. 채팅 자체가 바로 초기화되는 대상이기 때문입니다.

실제로 효과가 있었던 방법은 다음과 같습니다. 에이전트에게 채팅 외부에 읽고 쓸 수 있는 장소를 제공하는 것 — 그리고 그것을 제가 할 수 있는 가장 지루하고 내구성이 강한 것으로 만드는 것입니다. 바로 git 리포지토리(repo) 내의 일반 파일들입니다.

기질(Substrate): 에이전트가 세션 시작 시 읽는 markdown + YAML

open-bridge는 markdown과 YAML로 구성된 일반적인 git 리포지토리입니다. 매 세션이 시작될 때 에이전트는 이를 읽으므로, 이미 나의 환경을 알고 있는 상태에서 시작합니다. 데이터베이스도, SaaS도, 데몬(daemon)도, 호스팅할 것도 없습니다. 기질(substrate) 자체는 아무것도 실행하지 않습니다. 그저 에이전트가 읽는 파일들일 뿐입니다.

그 "그저 파일일 뿐"이라는 선택이 핵심입니다:

  • 에이전트는 파일을 읽을 수 있지만, API 키를 보유할 수는 없습니다. 제가 오늘 작성한 것을 에이전트는 6개월 후에도 여전히 읽을 수 있습니다. 마이그레이션도, 두 번째 앱도, 벤더 종속(vendor lock-in)도 필요 없습니다.
  • 감사가 가능합니다. 리포지토리를 클론(clone)하고 에이전트가 읽는 무엇이든 cat 명령어로 확인할 수 있습니다. 블랙박스가 없습니다.
  • 모델 및 도구에 구애받지 않습니다(model- and tool-agnostic). 일반 텍스트는 모든 에이전트 런타임(runtime)이 읽을 수 있는 것입니다.

그것이 어떤 모습인지 보여주는 아주 작은 조각입니다 (리포지토리의 examples/agency 설정에서 가져온 것 — 가상의 "Acme Dev"):

# ecosystem.yaml — 에이전트가 알아야 할 리포지토리/클라이언트
projects:
  bigcorp:    { display_name: "BigCorp E-Commerce", repos: [bigcorp-api, bigcorp-frontend] }
...

# work/board.md — 작업 디렉토리에서 생성되며, 매 세션마다 읽힘
## Doing
| bigcorp-api-payment-retry | incident | P1 | Stripe webhook retries failing |
...

따라서 제가 _"좋은 아침, 브리핑해줘"_라고 말할 때, 에이전트는 "GitHub인가요, Jira인가요?"라고 묻거나 잘못된 클라이언트 정보를 불러오지 않습니다. 이미 알고 있기 때문입니다.

이를 통해 얻을 수 있는 두 가지

저는 두 가지 아이디어에 의존합니다. 솔직히 말하면 이 둘은 파일들이 가능하게 하는 동작들에 붙인 이름일 뿐입니다.

항상 존재하는 컨텍스트 (Context). 에이전트는 매 세션마다 지속적이고 구조화된 레이어(layer)를 읽습니다. 즉, 당신의 저장소(repos), 클라이언트, 관례(conventions), 그리고 어제 무엇을 했는지를 읽습니다. 이는 모델(model)과 도구(tool) 사이에 존재하는 제3의 측면입니다. 이를 통해 에이전트는 질문을 멈추고, 추측을 멈추며, 잘못된 것을 다시 불러오는 일을 멈춥니다.

더미가 아닌 구조 (Structure). 제 AI 작업의 대부분은 예전에 그저 '내 문서' 폴더와 같았습니다. 모든 대화가 매번 새로운 더미(heap)로 쌓였죠. open-bridge는 평문(plain-text) 기반의 작업 시스템을 제공합니다. 보드(board), 일일 로그(daily log), 그리고 작업별 상태(backlog → doing → review → done)가 포함됩니다. 결정 사항과 발견 사항은 작업 진행 과정에서 파일로 저장되며, 에이전트는 나중에 이 텍스트를 다시 읽습니다. 비구조화된 세션들이 파일로 정리되어 축적되는 기록이 됩니다.

하나의 관례, 여러 에이전트

평문(plain text)이기 때문에 특정 도구에 종속되지 않습니다. 단일 skills/ 트리는 표준 스킬 심볼릭 링크(skill symlinks)를 통해 Claude Code, Codex, Copilot CLI에 의해 발견됩니다. 기질(substrate)은 동일하게 유지되며, 그 위에 올라가는 에이전트는 교체 가능합니다.

현재 상태에 대한 솔직한 고백

솔직하게 말씀드리고 싶은 부분은 이렇습니다. 이것은 아직 외부 사용자가 없는 단 하나의 셀프 호스팅 인스턴스 — 즉, 저의 것(BKS-Lab에서 구축)입니다. 저는 도입 성공 사례가 아니라, 방법론과 기질(substrate)을 공유하고 있는 것입니다. README에는 무엇이 검증되었는지, 무엇이 실험적인 시도인지, 그리고 무엇이 아직 구축되지 않았는지가 명확히 기재되어 있습니다. 만약 직접 시도해 보신다면, 어디에서 문제가 발생하는지 진심으로 듣고 싶습니다.

시도해 보기

  • 20초 워크스루 (20-second walkthrough) (실제 세션 재현): https://bks-lab.github.io/open-bridge/demo.html
  • 리포지토리 (Repo, MIT 라이선스): https://github.com/bks-lab/open-bridge
  • examples/agency/에 완벽하게 작동하는 설정이 준비되어 있습니다. 이를 클론(Clone)하여 에이전트에서 연 뒤, 아무런 컨텍스트(Context)를 붙여넣지 않고 리포지토리와 클라이언트, 그리고 태스크 보드(Task board)가 어떻게 구성되어 있는지 요약해 달라고 요청해 보세요. 단 한 번의 프롬프트(Prompt)로 이 모든 핵심 가치를 확인할 수 있습니다.

비결은 마크다운 (Markdown)과 YAML입니다. 이것이 전체 트릭이자, 이 프로젝트의 핵심입니다.

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0