Molayo

© 2026 Molayo

Dev.to헤드라인2026. 05. 27. 14:31

두 가지 지식 계층: AI 에이전트와 LLM을 위한 컨텍스트 구조화

요약

AI 에이전트와 런타임 LLM을 위한 두 가지 계층적 컨텍스트 구조화 전략을 제안합니다. 에이전트용 CLAUDE.md 계층 구조와 사용자 프로젝트용 TESTSMITH.md 컨벤션 파일을 통해 효율적인 정보 전달을 구현합니다.

핵심 포인트

  • CLAUDE.md를 활용한 에이전트용 계층적 코드베이스 지도 구축
  • 패키지 맵, 의존성 방향, 불변량을 통한 에이전트 컨텍스트 최적화
  • TESTSMITH.md를 통한 런타임 LLM용 프로젝트 컨벤션 주입
  • 불필요한 정보 노출을 줄여 토큰 효율성 및 정확도 향상

TestSmith에는 프로젝트에 대한 컨텍스트가 필요한 두 가지 별개의 대상이 있습니다. 바로 TestSmith 코드베이스
위에서 작동하며 (코드베이스 개발 및 확장을 도움) 작동하는 AI 에이전트와, 런타임 시
사용자의 프로젝트를 위해 테스트 코드를 생성하는 LLM입니다. 이들은 서로 다른 해결책이 필요한 서로 다른 문제입니다.

레이어 1: 에이전트 컨텍스트 — CLAUDE.md 계층 구조

AI 에이전트가 버그를 수정하거나 기능을 추가하기 위해 TestSmith를 열 때, 모든 파일을 읽지 않고도 코드베이스 구조를 이해해야 합니다. 하나의 거대한 컨텍스트 파일은 효과적이지 않습니다. 재시도(retry) 버그를 수정하는 에이전트가 Java 드라이버의 피스처(fixture) 생성 로직까지 알 필요는 없기 때문입니다.

해결책은 CLAUDE.md 계층 구조입니다:

CLAUDE.md                              ← 패키지 맵(package map), 불변량(invariants), 의존성 방향(dependency direction)
internal/domain/CLAUDE.md             ← 인터페이스(interfaces), 주요 타입(key types), "필드 추가" 체크리스트
internal/generation/CLAUDE.md         ← 파이프라인 데이터 흐름(pipeline data flow), 검증기 선택(verifier selection)
...

루트 파일은 지도입니다. 패키지별 파일은 실제 영역입니다. LLM 재시도 로직을 다루는 에이전트는 internal/llm/CLAUDE.md를 로드하며, 드라이버나 생성(generation) 관련 문서는 전혀 보지 않습니다.

루트 파일에는 작업과 관계없이 모든 에이전트에게 필요한 세 가지 요소가 포함됩니다:

  1. 패키지 맵 (Package map) — 각 내부 패키지가 무엇을 하는지, 그리고 어떤 파일을 먼저 읽어야 하는지
  2. 의존성 방향 (Dependency direction) — 엄격한 아키텍처 제약 조건 (domain은 다른 내부 패키지를 절대 임포트하지 않으며, drivers는 generation을 절대 임포트하지 않음)
  3. 불변량 (Invariants) — 모든 변경 사항에 걸쳐 반드시 참으로 유지되어야 하는 사항 (예: GeneratedFile.Language는 항상 설정되어야 함; resolveAction은 피스처 파일과 비피스처 파일에 대해 특정 규칙을 가짐)

패키지별 파일에는 "이 패키지를 건드리기 전에 이것을 읽으시오"라는 컨텍스트가 포함됩니다: 파이프라인을 위한 데이터 흐름 다이어그램, LLM 레이어를 위한 미들웨어 스택(middleware stack), 드라이버를 위한 어댑터 등록 패턴(adapter registration pattern) 등이 해당됩니다.

Claude Code가 패키지 내의 파일을 로드하면, 해당 패키지의 CLAUDE.md를 자동으로 읽습니다. 에이전트는 정확히 필요한 것만 얻게 되며, 그 이상의 불필요한 정보는 받지 않습니다.

Layer 2: 런타임 LLM 컨텍스트 (Runtime LLM Context) — TESTSMITH.md

이것은 TestSmith가 사용자의 프로젝트를 위한 테스트를 생성할 때 프롬프트(Prompt)에 주입하는 내용입니다. 이는 소스 코드와 함께 유지 관리하는 컨벤션(Conventions) 파일입니다.

생성 시점에 두 가지 수준이 병합됩니다:

<project-root>/TESTSMITH.md     ← 항상 로드됨; 프로젝트 전역 프레임워크, 모킹(Mock) 스타일
<source-dir>/TESTSMITH.md       ← 선택 사항; 패키지 수준의 오버라이드(Overrides)

루트(Root) TESTSMITH.md 예시:

# 프로젝트 컨벤션 (Project conventions)

Framework: pytest
...

src/services/payment/TESTSMITH.md에 있는 디렉토리별 오버라이드 예시:

# 결제 서비스 컨벤션 (Payment service conventions)
이 모듈은 Stripe와 통합됩니다. 모든 `stripe.*` 호출을 모킹(Mock)하세요.
HTTP 상호작용 테스트에는 `pytest.mark.vcr`을 사용하세요.

루트 파일은 시작 시 한 번 로드되어 ProjectContext에 캐싱됩니다. 디렉토리별 파일은 해당 디렉토리의 파일을 생성할 때만 지연 로딩(Lazily) 방식으로 병합됩니다. 대규모 모노레포(Monorepo)는 필요하지 않은 컨텍스트를 절대 로드하지 않습니다.

두 파일 모두 사용자 프롬프트(User prompt)가 아닌 시스템 프롬프트(System prompt)에 포함됩니다. 이는 사용자 프롬프트가 우선순위 기반의 트리밍(Trim)이 적용되는 설정 가능한 토큰 예산(PromptTokenBudget, 기본값 6,000 토큰)의 제한을 받기 때문에 중요합니다:

우선순위내용삭제 시점
1 (절대 삭제 안 됨)소스 코드 (Source code)삭제되지 않음
...

프로젝트 지식(Project knowledge)은 이 예산에서 완전히 제외됩니다. 소스 파일의 크기에 관계없이 시스템 프롬프트에 유지됩니다.

동적으로 추출된 컨벤션 (Dynamically Mined Conventions)

TESTSMITH.md 외에도, TestSmith는 동일한 디렉토리에 있는 기존 테스트에서 컨벤션을 추출합니다. 최대 5개의 파일, 총 80행까지 추출할 수 있습니다. 이를 통해 개발자가 컨벤션 문서를 별도로 유지 관리할 필요 없이, 모델에게 프로젝트의 테스트 스타일을 보여주는 실제 예시를 제공합니다.

이는 수동으로 작성된 가이드보다 비용이 저렴하고 정확합니다. 사용 중인 실제 테스트 패턴을 자동으로 반영하며, 테스트가 진화함에 따라 스스로 업데이트됩니다. 팀에서 새로운 어설션(Assertion) 패턴을 사용하기 시작하면, 다음 생성 실행 시 이를 즉시 반영합니다.

의존성 시그니처 인덱스 (The Dependency Signature Index)

세 번째 요소는 의존성 인덱스 (dep index)입니다. --all 실행이 시작될 때, TestSmith는 모든 소스 파일을 한 번씩 분석하여 modulePath → SourceAnalysis 맵을 구축합니다. payment.go를 위한 테스트를 생성할 때, payment.go가 임포트(import)하는 discount.go의 공개 API 시그니처 (public API signature)를 메모리에서 즉시 가져올 수 있습니다:

// 프롬프트 내부:
// 내부 의존성 시그니처 (Internal dependency signatures):
// discount.ApplyPromoCode(order Order, code string) (Order, error)
...

이를 통해 모델은 실제 인터페이스 (interface)가 어떻게 생겼는지 알게 되며, 임의로 만들어낸 것이 아닌 실제 시그니처와 일치하는 테스트 더블 (test doubles)을 생성할 수 있습니다.

워치 모드 (watch mode)에서는 파일이 변경될 때 해당 파일의 엔트리만 새로고침됩니다. 나머지 인덱스는 재생성 사이에도 계속 유지(warm)됩니다.

분리가 중요한 이유

두 계층은 서로 다른 문제를 해결합니다:

  • **에이전트 컨텍스트 (Agent context)**는 개발 시간 (development-time) 탐색에 관한 것입니다. 이는 계층적이고 사람이 읽기 쉬우며, 선택적으로 로드됩니다. 아키텍처 (architecture)와 불변량 (invariants)을 설명합니다. 레포지토리 (repo) 내에 존재하며, 설명하는 코드와 함께 유지 관리됩니다.

  • **런타임 LLM 컨텍스트 (Runtime LLM context)**는 생성 시간 (generation-time) 품질에 관한 것입니다. 이는 두 수준에서 병합되어 시스템 프롬프트 (system prompts)에 주입되며, 토큰 예산 (token budgets)의 제한을 받지 않습니다. 대상 프로젝트에 특화된 컨벤션 (conventions)과 패턴 (patterns)을 설명하며, 이는 LLM이 소스 코드만으로는 추론할 수 없는 것들입니다.

두 가지를 혼동하면 시스템 프롬프트가 비대해지거나 (모든 생성 요청에 에이전트 컨텍스트를 쏟아붓는 경우), 에이전트에게 정보가 부족해지는 (아키텍처 가이드 없이 사용자 대상 컨벤션 문서만 제공하는 경우) 결과로 이어집니다. 이들을 분리하여 유지한다는 것은 각 대상에게 정확히 필요한 것만을 제공한다는 의미입니다.

다음: Go CLI를 출시하며 겪었던 크로스 플랫폼 버그 — 탐지기 경계 탈출 (detector boundary escapes) 및 Windows 경로 구분자 문제.

AI 자동 생성 콘텐츠

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

원문 바로가기
0

댓글

0