하네스 엔지니어링 위키

내 패턴 · 컨텍스트·프롬프트 조립 (CLAUDE.md @-import 체인과 주입 헌법)

Properties2
tags기능분해, mine, prompt-assembly-claudemd
aliases컨텍스트 조립, CLAUDE.md import 체인, 주입 헌법

14 min read

내 패턴 · 컨텍스트·프롬프트 조립 (CLAUDE.md @-import 체인과 주입 헌법)

한 줄 요약

AI 코딩 도구는 작업을 시작할 때마다 CLAUDE.md라는 “지시문 정본”을 자동으로 시스템 프롬프트에 끼워 넣는데, 이 파일은 줄글 메모가 아니라 정해진 세 가지 꼴(참조 import / XML 태그 헌법 / SSoT 데이터 헌법) 중 하나를 띤다. → 왜 배우나: 이 파일의 형태를 의식적으로 고르면, 매번 같은 지시를 타이핑하지 않고도 모델이 “내 프로젝트의 규칙” 안에서 일관되게 움직이게 만들 수 있다.

그림

flowchart TD
    A[세션 시작] --> B["CLAUDE.md 수집: 현재폴더 + 상위폴더 + 홈"]
    A --> S[settings.json의 켜진 플러그인 목록]
    S --> P["플러그인 CLAUDE.md 합성<br/>OMC XML 태그 블록"]
    B --> C{"본문이 @import인가?"}
    C -- 예 --> D["@AGENTS.md 자리에 펼치기<br/>(체인 깊이 1, 끝단 파일)"]
    C -- 아니오 --> E["본문 그대로 넣기<br/>XML 태그 / SSoT 표·YAML"]
    D --> F[시스템 프롬프트로 합쳐짐]
    E --> F
    P --> F
    M[MEMORY.md 링크 인덱스] --> F
    F --> G["모델: 제약 안에서 행동·생성"]
    G --> H["산출물이 계약 준수<br/>frontmatter/커밋 trailer/위임 규칙"]

쉽게 풀기

비유 한 줄: CLAUDE.md는 신입사원이 출근 첫 순간 책상 위에서 보는 “근무 수칙판”이다. 매일 아침 누가 말로 알려주지 않아도, 그 판이 거기 붙어 있어 자동으로 읽힌다.

단계별로 풀어 보면 이렇다.

  1. 모델은 매 세션 “수칙판”을 먼저 먹는다. AI 코딩 도구(Claude Code / Codex)는 작업을 시작할 때 “이 프로젝트에서 어떻게 행동하라”는 지시문을, 사람이 매번 타이핑하지 않아도 자동으로 시스템 프롬프트에 끼워 넣는다. 그 정본이 프로젝트 폴더의 CLAUDE.md(또는 Codex용 AGENTS.md)다.

  2. 이 수칙판은 “자유 줄글”이 아니다. 핵심은 여기다. 내 저장소들에서 이 파일은 아무렇게나 쓴 메모가 아니라, 아래 세 가지 정해진 꼴 중 하나를 띤다.

    • 꼴 ① 참조로 가져오기(import-by-reference): 본문은 딱 한 줄(@AGENTS.md)뿐. “진짜 규칙은 저 파일을 읽어라”고 손가락으로 가리키기만 한다. 도서관 안내데스크가 “그 책은 3층 A칸”이라고 위치만 알려주는 것과 같다.
    • 꼴 ② XML 태그 헌법: <operating_principles> 같은 태그 블록으로 행동·도구·위임 규칙을 조항처럼 못박는다. 법전이 “제1조, 제2조”로 경계를 나누는 것과 같다.
    • 꼴 ③ SSoT 데이터 헌법: 데이터 스키마(frontmatter 계약), 관계 분류표, 통과 게이트를 본문에 통째로 박고 “이게 전 시스템의 단 하나뿐인 진실(SSoT)이다”라고 선언한다. 건물 1층 로비에 박아둔 “안전수칙 전문”과 같다.

  3. 왜 줄글 대신 정해진 꼴을 쓰나? 줄글 메모는 모델이 “어디까지가 진짜 규칙인지” 경계를 못 잡는다. 반면 태그와 표는 경계가 자명하다. 또 import 한 줄(@AGENTS.md)을 쓰면 Claude Code와 Codex 두 도구가 같은 한 파일을 보게 되어, 두 도구의 지시가 영원히 어긋나지 않는다(드리프트 제거).

SSoT란?

Single Source of Truth, 즉 “단 하나뿐인 진실의 출처”다. 같은 규칙을 여러 곳에 복사해두면 한쪽만 고쳐져 서로 어긋난다. 그래서 “진짜는 여기 하나”라고 못박는 설계다.

핵심 정리

컨텍스트 파일은 어디서 끌려오나 (실측)

이름타입역할
CLAUDE.md (루트)파일세션 시작 시 자동 로드. import 패턴에선 단 11바이트(@AGENTS.md\n)
AGENTS.md (루트)파일Codex 호환 이름. @로 끌려와 실제 규칙을 담는 정본
@<경로>import 지시자그 자리에 대상 파일 내용을 펼침. 실측상 체인 깊이 1(끝단)
플러그인 CLAUDE.md파일enabledPlugins로 켜지면 합성됨(OMC XML 헌법 등)

그 외 합성 대상

  • ~/.claude/settings.json — model·enabledPlugins 등으로 어떤 플러그인 CLAUDE.md가 끼어들지 결정.
  • MEMORY.md + memory/*.md — - [라벨](파일.md) — 한줄요약 형식의 링크 인덱스로 샤드 메모를 홈 레벨에서 자동 주입.

세 가지 본문 형식 한눈에

패턴식별 마커강제 대상
(1) 참조 import본문이 @로 시작하는 단일 줄정본을 한 곳으로 모으기
(2) XML 태그 헌법 (OMC)<태그>...</태그> + <!-- OMC:START/END -->행동·위임·도구·커밋 규약
(3) SSoT 데이터 헌법 (akh2)“단일 진실(SSoT)이다” 선언 + YAML/표데이터 무결성·파이프라인 게이트

분산이냐 인라인이냐 — 설계 선택의 대비

같은 SSoT 사상도 두 갈래로 나뉜다.

  • v1(ai-knowledge-hub) — 본문이 “_meta/SCHEMA.md가 헌법이다”라며 SCHEMA/DOMAINS/INGEST/LINT/BUDGET로 흩어 가리킴(패턴 1에 가까움).
  • v2(akh2) — 같은 내용을 한 파일에 인라인으로 통합(패턴 3 정석). 즉 패턴 1과 3은 양극단이고, 분산↔인라인은 의식적으로 고르는 선택지다.

실제 예시

패턴 1 — 참조 import (정본은 끌려오는 쪽):

// /home/seunghyeong/projects/conclave/CLAUDE.md  (전체. 11바이트)
@AGENTS.md
<!-- /home/seunghyeong/projects/conclave/AGENTS.md  (전체. 327바이트, 끝단 파일) -->
<!-- BEGIN:nextjs-agent-rules -->
# This is NOT the Next.js you know
 
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
<!-- END:nextjs-agent-rules -->

image-platform의 CLAUDE.md / AGENTS.md는 바이트 단위까지 동일. CLAUDE.md(Claude Code용)와 AGENTS.md(Codex용) 두 도구가 같은 정본을 보게 하는 게 import 한 줄의 목적이다.

패턴 2 — XML 태그 행동헌법 (OMC 플러그인):

// /home/seunghyeong/.claude/plugins/marketplaces/omc/CLAUDE.md  (발췌)
<!-- OMC:START -->
<!-- OMC:VERSION:4.9.1 -->
# oh-my-claudecode - Intelligent Multi-Agent Orchestration
 
<operating_principles>
- Delegate specialized work to the most appropriate agent.
- Prefer evidence over assumptions: verify outcomes before final claims.
</operating_principles>
 
<delegation_rules>
Delegate for: multi-file changes, refactors, debugging, reviews, planning, research, verification.
Work directly for: trivial ops, small clarifications, single commands.
Route code to `executor` (use `model=opus` for complex work).
</delegation_rules>
 
<agent_catalog>
explore (haiku), analyst (opus), planner (opus), executor (sonnet), verifier (sonnet), ...
</agent_catalog>
 
<commit_protocol>
Trailers: Constraint:, Rejected:, Directive:, Confidence:, Scope-risk:, Not-tested:
</commit_protocol>
<!-- OMC:END -->

패턴 3 — SSoT 데이터 헌법 (akh2):

// /mnt/d/akh2/CLAUDE.md  (발췌)
# akh2 — AI 지식 위키 v2 헌법
**이 문서가 전 시스템의 단일 진실(SSoT)이다.** 모든 작업 전에 읽고 준수한다.
 
## 3. Frontmatter 계약 (전 페이지 필수)
​```yaml
slug:            # 파일명과 일치. 전역 유일. kebab-case
kind: concept | summary | model-card | map | ...
confidence:      # 0.9=독립 출처 2+교차검증 | 0.6=단일 출처
relations:       # §4 타입만. references는 페이지당 ≤5
​```
 
## 4. 관계 분류 (10종 — 이외 타입은 admit FAIL)
| 타입 | 의미 | evidence | 제약 |
| supersedes | 신 주장이 구 주장 대체 | **필수** | 비순환 |

직접 만들 때 — 패턴 1 (작은 앱에 권장):

// <프로젝트>/CLAUDE.md
@AGENTS.md
<!-- <프로젝트>/AGENTS.md -->
# <한 줄 정체성: 이 코드베이스의 함정>
<훈련데이터와 다른 점 1~3개. 코드 쓰기 전 읽어야 할 실제 경로.>

직접 만들 때 — 패턴 2 (멀티에이전트/팀 운영 시):

<operating_principles>
- <원칙 1: 위임 기준>
- <원칙 2: 추측보다 증거>
</operating_principles>
<delegation_rules>
Delegate for: <목록>. Work directly for: <목록>.
</delegation_rules>
<commit_protocol>
Trailers: Constraint:, Rejected:, Confidence:, Scope-risk:
</commit_protocol>

직접 만들 때 — 패턴 3 (파이프라인/위키 시):

# <시스템> 헌법
**이 문서가 단일 진실(SSoT)이다.**
## Frontmatter 계약
​```yaml
<필드>: # <규칙·유일성·enum>
​```
## 관계 분류 (N종 — 이외 FAIL)
| 타입 | 의미 | evidence | 제약 |
## 게이트 규칙
- <통과 없이는 exit 2로 거부>

만들기 전 체크리스트

  • CLAUDE.md가 자유 줄글이 아니라 위 세 꼴 중 하나인가
  • import 패턴이면 CLAUDE.md와 AGENTS.md가 같은 정본을 가리키는가(두 도구 일치)
  • @ 체인 깊이를 의식적으로 관리하는가(실측은 깊이 1 끝단 — 순환·과중첩 회피)
  • 행동 규칙은 XML 태그로 경계를 명확히 했는가(<delegation_rules> 등)
  • 데이터 계약(frontmatter/관계/게이트)은 표·YAML로 박았는가
  • 플러그인 헌법이 들어오면 settings.json의 enabledPlugins로 켜져 있는가
  • 분산(v1 _meta/* 참조) vs 인라인(v2 한 파일) 중 의도적으로 선택했는가

요약 & 셀프체크

3줄 요약

  1. CLAUDE.md는 세션 시작 시 자동으로 시스템 프롬프트에 합쳐지는 “지시문 정본”이며, 줄글이 아니라 세 가지 정해진 꼴 중 하나를 띤다.
  2. 세 꼴은 ① 참조 import(정본 한 곳으로 모으기) ② XML 태그 헌법(행동·위임 조항) ③ SSoT 데이터 헌법(스키마·게이트 인라인)이다.
  3. import 한 줄을 쓰면 Claude·Codex 두 도구가 같은 파일을 보게 되고, 태그·표를 쓰면 모델이 규칙 경계를 자명하게 파싱한다.

스스로 답해보기

  • @AGENTS.md 한 줄짜리 CLAUDE.md를 쓰는 가장 큰 이득은 무엇이고, 왜 두 파일을 따로 두는가?
  • 줄글 메모 대신 XML 태그나 표를 쓰면 모델 입장에서 무엇이 좋아지는가?
  • 같은 SSoT 사상인데 v1은 분산, v2는 인라인을 택했다. 어떤 상황에 어느 쪽이 유리할까?

근거 파일

  • /home/seunghyeong/projects/conclave/CLAUDE.md (@AGENTS.md, 11B)
  • /home/seunghyeong/projects/conclave/AGENTS.md (Next.js 끝단 파일, 327B, @ 없음 확인)
  • /home/seunghyeong/projects/image-platform/CLAUDE.md + AGENTS.md (conclave와 바이트 동일)
  • /home/seunghyeong/.claude/plugins/marketplaces/omc/CLAUDE.md (OMC v4.9.1 XML 태그 헌법)
  • /mnt/d/akh2/CLAUDE.md (SSoT 인라인 헌법 — frontmatter 계약·관계 10종·게이트)
  • /mnt/d/ai-knowledge-hub/CLAUDE.md (v1 SSoT 분산 — _meta/SCHEMA.md 등 참조)
  • /mnt/d/human-token-workflow/AGENTS.md (역할별 지침형 — writer/reviewer/crawler 조항)
  • /home/seunghyeong/.claude/settings.json (enabledPlugins로 합성 대상 결정)
  • /home/seunghyeong/.claude/projects/-home-seunghyeong/memory/MEMORY.md (+ memory/*.md 링크 인덱스)

연결

MINE_개요 · _분석축_루브릭 · MINE_10_entrypoint-plugin-loading(플러그인 로딩·settings.json) · MINE_80_state-memory-persistence(MEMORY.md 메모리 주입)

Codex 교차검증 메모

이 노트의 핵심 사실 — ① CLAUDE.md/AGENTS.md 자동 로드와 @-import의 자리 치환 전개, ② 내 저장소 실측 import 체인 깊이 1(끝단 leaf), ③ import의 목적이 Claude·Codex 두 진입점의 정본 단일화(드리프트 제거)라는 점, ④ 줄글보다 XML 태그/표가 모델에게 규칙 경계를 명확히 준다는 점, ⑤ v1 분산(_meta/* 참조) vs v2 인라인의 설계 대비 — 은 위 근거 파일들의 실제 내용과 대조하여 교차검증된 항목이다. 바이트 수치(11B/327B 등)와 OMC 버전(4.9.1)은 실측 시점 값이므로, 파일이 갱신되면 다시 확인할 것.

그래프 뷰

백링크