Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
코딩 에이전트가 이전 세션의 맥락을 잃고 이미 결정된 사항을 재질문하거나 잘못된 코드를 생성하는 문제를 해결하기 위해 'Fragment'라는 파일 기반 프로토콜을 제안합니다. 이 방식은 단순한 메모를 넘어, 규칙과 상태를 담는 전용 파일을 활용하고 CI(Continuous Integration) 가드 시스템을 도입하여 정보의 진실성을 강제합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기가장 단순한 형태로 이 패턴을 설명하겠습니다. 월요일에 당신은 에이전트에게 이렇게 말합니다: '이메일 회원 가입은 없습니다. 사용자 대부분이 이메일 주소를 가지고 있지 않으니 전화번호로 합니다.'
목요일에는 새로운 세션이 열리면서 다음과 같은 질문을 받습니다: '시작하기 전에 — 회원가입에 이메일을 사용해야 하나요, 아니면 전화번호를 사용해야 하나요?'
누구도 잘못한 것은 없습니다. 결정은 내려졌고, 그 근거 또한 합당했습니다. 단지 더 이상 존재하지 않는 채팅 창 안에 머물렀을 뿐입니다. 새 세션은 코드를 읽어보고 이메일에 관한 내용을 보지 못하자, 당연하게 질문을 던진 것입니다. 때로는 묻지 않고, 제가 이미 거부했던 버전을 그저 만들어내기도 했습니다.
만약 당신이 매일 코딩 에이전트와 작업한다면, 아마도 모든 세션 시작 시마다 작은 연설문을 타이핑하기 시작했을 겁니다. '작은 가게입니다. 회원가입은 전화번호로 합니다. 가격 코드는 건드리지 마세요. 그 버그는 두 번이나 수정했습니다. 결제 과정은 실패한 결제가 무엇을 보여줘야 할지 아직 결정하지 못해서 멈춰 있습니다.' 매번 다른 부분을 잊게 되고, 당신이 잊어버리는 부분이 바로 시스템을 망가뜨리는 부분입니다.
저는 프론트엔드 및 모바일 엔지니어입니다. 제 업무 시간의 대부분은 프로덕션 환경의 React와 React Native 앱에 할애되며, 최근에는 Claude Code와 Codex로 인해 많은 부수적인 작업도 진행했습니다. 제가 원했던 것은 간단했습니다: 세션의 마지막 5분은 기억이 아니라 파일을 생성하는 것이었습니다.
그 결과물이 Fragment가 되었습니다. 이것은 아무것도 실행하는 도구가 아닙니다. 리포지토리 안에 있는 몇 개의 일반 파일들입니다:
docs/AGENT-PROTOCOL.md 규칙을 담는 파일. 모든 에이전트와 사람이 읽습니다.
CLAUDE.md / AGENTS.md 각각 세 줄로, 해당 파일을 가리킵니다. 두 번째 사본은 절대 없습니다.
docs/STATE.md 보드 역할을 합니다. 가장 먼저 읽고, 가장 나중에 작성합니다.
...
STATE.md에는 **
저는 '노트 파일 유지' 방식을 시도해 봤습니다. 이 방식은 약 5일 동안 작동합니다. 하지만 어느 세션에서는 업데이트하는 것을 잊고, 다음 세션에서는 오래된 정보를 신뢰하게 되며, 결국 처음의 문제로 돌아가게 됩니다.
따라서 중요한 부분은 폴더 구조 자체가 아닙니다. '가드(guard)'입니다. docs-check.sh는 다음과 같은 경우 CI를 실패시킵니다:
이 가드는 사용자의 코드나 언어에 대해서는 아무것도 알지 못합니다. 오직 이야기가 진실을 유지하고 있는지 여부만 확인합니다. 저장소별 규칙은 공유 가드에서 가져오는 로컬 파일에 들어있기 때문에, 가드를 업데이트해도 이 규칙들은 건드리지 않습니다.
Fragment는 처음부터 설계된 것이 아니라 비공개 저장소에서 추출되었습니다. 두 명의 사람, 두 개의 운영체제, 두 개의 다른 에이전트가 18시간 동안 25개의 커밋을 했습니다. 저를 놀라게 한 점은 두 가지였습니다:
첫 번째: 이 가드는 CI에 연결된 지 74분 만에 실제 사고를 포착했습니다. GitHub 웹 UI를 통해 파일 이름이 변경되었습니다. 완벽하게 합리적인 정리 작업이었지만, 이 이름 변경 하나가 세 가지 규칙을 동시에 깨뜨렸습니다. 즉, 단절된 인덱스 링크, 목록에 없는 파일, 건너뛴 세션 로그였습니다. CI는 몇 분 만에 빨간불이 켜졌습니다. 아무도 부주의했던 것이 아닙니다. 웹 UI는 자신이 존재한다는 것을 모르는 인덱스는 볼 수 없기 때문입니다.
두 번째: 두 번째 사람은 교육받지 않았음에도 이 의식을 채택했습니다. 그가 한 모든 커밋은 동일한 세 개의 파일 구조를 가졌습니다: 인덱스, 보드, 실제 작업물. 공유된 세션도, 상기 알림도 없었습니다. 그는 같은 프로토콜 파일을 읽고 동일한 움직임에 수렴했습니다.
이것을 미리 말씀드리는 것이 낫겠습니다. 자신만 자랑하는 사례 연구는 마케팅일 뿐이니까요:
전체 작동 버전과 커밋 SHA는 CASE-STUDY.md에서 확인할 수 있습니다.
Claude Code에서는:
npx skills add hematenergi/fragment --skill fragment
또는 사이트에서 설치 프롬프트를 복사하여 이미 사용 중인 에이전트에 붙여넣으세요. guard를 처음 실행하면 실패할 것입니다. 이것이 기능입니다: 일종의 도입 체크리스트 역할을 합니다. 목록을 따라가며 초록색(green)으로 만들 때까지 작업하세요.
만약 시도해 보고 작동하지 않는 부분이 있다면, 어디서 문제가 발생했는지 알려주세요.
저는 인도네시아에 거주하는 프론트엔드 및 모바일 엔지니어 Dany입니다 (GMT+7): React, Next.js, React Native, 그리고 웹3 프론트엔드(Solana, EVM)를 다룹니다. 또한 AI 코딩 에이전트를 위한 툴링도 만듭니다. 원격 계약직 업무에 열려 있습니다 — hematenergi.github.io.