Claude Code로 구축한 LLM 컴파일 지식 베이스 스키마 표준 (AGENTS.md)

실용적 조언

에이전트 세션 시작 시 AGENTS.md와 같은 명세 파일을 읽게 하여 작업의 일관성을 확보할 수 있다.
복잡한 RAG 시스템 구축 대신 마크다운 백링크와 인덱싱 구조를 활용해 지식 검색 효율을 높일 수 있다.

섹션별 상세

AGENTS.md 스키마는 에이전트가 지식 베이스를 관리하는 표준 운영 절차를 정의한다. 에이전트는 세션 시작 시 이 파일을 읽어 디렉토리 구조, 파일 명명 규칙, 린팅 워크플로우를 파악하고 일관된 동작을 수행한다. 이 방식은 별도의 데이터베이스 없이 마크다운 파일만으로 복잡한 지식 체계를 유지할 수 있게 한다. 실무적으로는 에이전트의 출력 품질을 제어하고 지식 오염을 방지하는 가이드라인 역할을 한다.

기존 RAG 방식 대신 구조화된 마크다운 위키와 에이전트의 추론 능력을 결합했다. 에이전트는 원시 소스를 분석하여 개념 문서를 작성하고, 문서 간 백링크와 인덱스 파일을 자동으로 생성하여 지식 간 연결성을 확보한다. 작성자는 수개월간의 반복 실험을 통해 벡터 DB 없이도 충분히 정교한 지식 검색과 정리가 가능함을 확인했다. 이는 인프라 복잡도를 낮추면서도 에이전트의 컨텍스트 이해도를 극대화하는 전략이다.

지식 정리를 넘어 실제 습득을 돕는 '학습 레이어'가 통합되었다. 에이전트는 작성된 개념 문서에서 플래시카드를 자동 생성하고, FSRS 알고리즘을 사용하여 간격 반복 학습 큐를 관리한다. 또한 린팅 과정에서 발견된 지식 공백을 추적하여 사용자가 보완해야 할 부분을 명시적으로 제시한다. 단순한 저장소를 넘어 사용자의 인지적 성장을 지원하는 시스템으로 설계되었다.

Claude Code는 스키마 반복 개선과 대규모 파일 생성 작업을 가속화했다. 약 50개의 레포지토리 파일을 작성하는 과정에서 스키마와 실제 구현 간의 불일치를 잡아내는 디버깅 도구로 활용되었다. 단일 세션 내에서 AI 정렬 주제의 예시 위키를 통째로 구축하는 성능을 보여주었다. 이는 코딩 에이전트가 단순 코드 작성을 넘어 복잡한 지식 아키텍처를 구현하는 데 유용함을 입증한다.

용어 해설

검색 증강 생성(RAG): — 검색 증강 생성(Retrieval-Augmented Generation)의 약자로, 외부 데이터베이스에서 관련 정보를 검색하여 LLM의 답변에 포함시키는 기술이다. 본 프로젝트에서는 이 대신 마크다운 구조화를 통해 에이전트의 컨텍스트 이해도를 높이는 방식을 선택하여 시스템 복잡도를 낮추고 데이터 제어력을 확보했다.
자유 간격 반복 스케줄링(FSRS): — 자유 간격 반복 스케줄링(Free Spaced Repetition Scheduler) 알고리즘으로, 사용자의 학습 이력을 바탕으로 망각 곡선을 예측하여 최적의 복습 시점을 계산한다. 지식 베이스 내 플래시카드 시스템에 적용되어 단순한 정보 저장을 넘어 장기 기억 형성을 돕는 핵심 메커니즘으로 작동한다.
린팅(Linting): — 작성된 문서나 코드의 오류, 스타일 불일치, 논리적 모순 등을 자동으로 검사하는 과정이다. 이 시스템에서는 에이전트가 생성한 지식 문서들 사이의 모순을 찾아내고 지식의 공백을 식별하여 전체 지식 베이스의 품질과 일관성을 유지하는 파이프라인 역할을 수행한다.
스키마(Schema): — 데이터의 구조와 형식을 정의하는 명세로, 여기서는 에이전트가 지식 베이스를 관리하는 규칙인 AGENTS.md를 의미한다. 에이전트가 세션마다 이 파일을 읽어 일관된 워크플로우를 유지하도록 돕는 설계 도면 역할을 한다.

언급된 도구

Claude Code추천

지식 베이스 구축 및 스키마 반복 개선

Claude추천

원시 소스 분석 및 개념 문서 작성

언급된 리소스

GitHubllm-knowledge-base GitHub Repository