AGENT_GUIDE 체계를 3 층으로 해부하기 — Cross-cutting Concern 과 아키텍트·아키텍처

이 블로그 프로젝트의 AGENT_GUIDE 가 Prompt·Context 만 설계하고 Harness 는 차용하는 구조, 그리고 Skill-based PE 가 왜 세 층을 횡단하는 cross-cutting 인가

이전 포스트에서 정의한 Prompt·Context·Harness 3 층위를 이 블로그 프로젝트의 AGENT_GUIDE 체계 에 적용해 해부한다. 이 프로젝트는 Prompt + Context 두 층을 적극적으로 설계하지만 Harness 는 Claude Code·Gemini CLI 의 기본값을 차용한다. 하네스를 만들지 않으면서도 하네스의 한계를 의식해 방어하는 패턴을 Harness-aware Context Engineering 이라 명명한다. 또한 “Skill-based Prompt Engineering 이 세 층을 관통하는 것처럼 보이는” 혼란을 소프트웨어 공학의 cross-cutting concern 개념으로 정리하고, 아키텍트 (설계자) 와 아키텍처 (설계 결과물) 를 구분한다.

Agent
Architecture
Engineering
저자

Kwangmin Kim

공개

2026년 04월 16일

1 출발 질문

이전 포스트 Prompt · Context · Harness Engineering — 세 층위의 구분과 포함 관계 에서 세 층위를 동심원으로 정의했다. 그 다음 자연스럽게 나오는 질문이 있다.

“그럼 이 블로그 프로젝트의 AGENT_GUIDE 체계는 어느 층에 속하는가?”

표면만 보면 “skill-based prompt engineering” 이다. 그런데 AGENT_GUIDE 가 실제로 하는 일을 뜯어보면 Prompt 층에 국한되지 않는다. 라우팅 테이블, Phase 프로토콜, info-search 3-Layer 병렬 탐색, 절대 규칙의 중복 배치 등은 Context Engineering 이다. 반면 Auto-compaction 이나 Protected zone 같은 Harness Engineering 은 Claude Code·Gemini CLI 의 기본값을 그대로 쓴다.

이 글은 AGENT_GUIDE 체계를 3 층 관점으로 해부하고, 그 과정에서 두 가지 개념을 정리한다.

  • Harness-aware Context Engineering — 하네스를 만들지 않으면서도 의식하는 방어적 설계
  • Cross-cutting concern — Skill-based PE 가 여러 층을 횡단하는 현상을 소프트웨어 공학 용어로 정식화

마지막으로 아키텍트 (설계자) 와 아키텍처 (설계 결과물) 를 구분해 이 프로젝트의 설계 구조를 명명한다.

2 AGENT_GUIDE 가 실제로 하는 일 — Prompt + Context 두 층

AGENT_GUIDE 체계의 각 활동을 3 층위에 매핑하면 다음과 같다.

활동 해당 층
각 skill 파일 안의 지시 (한다 체, Self-Check 항목, 루브릭 등) Prompt
스타일 규칙 (수동 번호 금지, 이모지 금지, YAML 필수 필드) Prompt
튜터 루브릭 (writing-rubric-lv{N}.md, sql-weakness.md) Prompt
AGENT_GUIDE.md 의 라우팅 테이블 — 어느 커맨드에 어느 가이드를 로드할지 Context
Phase 0~4 프로토콜 — 가이드를 어떤 순서로 읽을지 Context
info-search.md 3-Layer 병렬 탐색 — 무엇을 먼저 보여줄지 Context
절대 규칙 5 개를 CLAUDE.md + AGENT_GUIDE.md + CORE 에 중복 배치 Context
CP-1/CP-2/CP-3 체크포인트 — “읽었음을 명시 출력하라” Context
common-mistakes.md 에 오류 패턴 누적 Context (메모리 전략)

Prompt 층 — 답변의 형식·톤·품질 기준을 정하는 지시문. skill 파일 내부의 모든 구체적 지시가 여기 속한다.

Context 층 — 세션마다 모델이 무엇을·언제·얼마나 보게 할지 결정하는 규칙. 이게 바로 AGENT_GUIDE 체계의 핵심 설계 영역 이다.

그래서 정확한 명명: 이 프로젝트는 Skill-based Prompt + Context Engineering 을 한다. “prompt” 라는 이름 때문에 prompt 층만 다루는 것처럼 들리지만, 실제로는 Context 층이 설계 비중의 절반 이상이다.

3 AGENT_GUIDE 가 하지 않는 일 — Harness Engineering 은 차용

반대로 Harness 층의 메커니즘은 전부 남이 만든 것을 가져다 쓴다.

Harness 활동 이 프로젝트에서 하는가 어디서 오는가
Auto-compaction 알고리즘 설계 안 함 Claude Code 내부 로직
Tool result lifecycle 정책 결정 안 함 하네스 기본값
Protected zone 구현 안 함 Gemini CLI 가 내부적으로 처리
응답 길이 제약 설정 안 함 Claude Code 시스템이 25/100 단어 강제
Skill 로딩 정책 (eager vs lazy) 안 함 Claude Code Skill tool 구현
Subprocess 인터페이스 설계 안 함 claude, gemini CLI 규약
Tool loop 정책 안 함 하네스 기본

이 프로젝트는 Harness Engineering 을 하지 않는다. Claude Code, Gemini CLI 라는 이미 만들어진 하네스 위에 얹어 쓴다. 하네스 자체의 거동은 블랙박스 그대로 두고, 그 위에서 Prompt + Context 만 설계한다.

이게 옳은 선택인 이유는 명확하다. Harness Engineering 은 런타임·컴파일러 수준의 엔지니어링 으로, Anthropic·GitHub·Google 같은 대기업 팀이 전담하는 영역이다. 개인 블로그 프로젝트가 손대면 과잉 엔지니어링이 된다.

4 이 프로젝트의 정확한 위치

3 층 동심원에 이 프로젝트의 설계 범위를 표시하면 다음과 같다.

┌─────────────────────────────────────────────┐
│  Harness (Claude Code / Gemini CLI)         │  ← 차용 (남이 만든 것)
│                                             │
│  ┌─────────────────────────────────────┐   │
│  │  Context Engineering                │   │  ← 이 프로젝트가 설계
│  │  (AGENT_GUIDE 라우팅, Phase 0~4,   │   │
│  │   info-search 3-Layer,              │   │
│  │   중복 배치·CP 체크포인트 전략)    │   │
│  │                                     │   │
│  │  ┌───────────────────────────┐     │   │
│  │  │  Prompt Engineering       │     │   │  ← 이 프로젝트가 설계
│  │  │  (skill 파일 지시문,       │     │   │
│  │  │   한다 체, 루브릭,         │     │   │
│  │  │   스타일 규칙)             │     │   │
│  │  └───────────────────────────┘     │   │
│  └─────────────────────────────────────┘   │
└─────────────────────────────────────────────┘

설계 영역: 안쪽 두 층 차용 영역: 가장 바깥 하네스 층

5 Harness-aware Context Engineering — 새로운 패턴 이름

여기서 흥미로운 점이 있다. 이 프로젝트는 Harness Engineering 을 하지 않지만, 하네스의 한계를 깊이 의식하고 방어한다.

5.1 구체 방어 기제 3 가지

  1. 경고 문구 내재화 — CLAUDE.md 자체에 다음 문구가 있다:

    “Claude Code 는 규칙을 자체 요약·압축하거나, 단계를 건너뛰는 경향이 있다.”

    이건 하네스의 압축 정책을 사용자 가이드에 드러내서 모델이 자기 경향을 자각하도록 만든 방어적 서술이다.

  2. 절대 규칙 5 개의 중복 배치 — “한다 체, 수동 번호 금지, Category GUIDE 로드, index 업데이트, 이모지 금지” 5 개 규칙이 다음 세 곳에 동일하게 인용 된다:

    • CLAUDE.md 상단
    • AGENT_GUIDE.md (핵심 규칙 섹션)
    • guides/AGENT_GUIDE_CORE.md 절대 규칙 5 개 섹션

    이건 정보 설계 원칙상 “redundancy 를 제거하라” 에 위배된다. 그러나 의도된 redundancy 이다 — 하네스의 auto-compaction 이 일부 파일 내용을 요약해도, 세 곳 중 최소 한 곳은 살아남을 확률을 높이는 방어적 중복.

  3. CP-1/CP-2/CP-3 출력 의무 — “가이드 로드 확인 / Step 명시 / Self-Check 출력” 세 체크 포인트는 모델이 읽었다는 사실만 기억하지 않고 읽은 내용을 응답 텍스트로 출력하게 강제한다. 출력된 텍스트는 사용자 메시지 스트림에 남아 auto-compaction 으로 사라지기 어렵다. 즉 모델 응답 자체를 정보 보존 매체로 활용 한다.

5.2 패턴 명명

이 세 기제의 공통점은 “하네스의 거동을 고칠 수 없으므로, 그 거동을 예측하고 Context 설계 로 방어” 한다는 것이다. 이런 설계 패턴에 이름이 필요하다.

Harness-aware Context Engineering — 하네스 내부 메커니즘을 직접 만들지 않지만, 그 메커니즘의 한계·편향·부작용을 예측해 Context 층에서 방어적으로 설계하는 접근.

비유하자면 운영체제를 만들지 않지만, 운영체제의 메모리 관리 정책을 알고 있어서 자기 프로그램이 swap out 되지 않도록 hot path 를 inline 으로 쌓는 프로그래머와 같다. OS 엔지니어 는 아니지만 OS-aware 프로그래머다.

6 Skill-based PE 는 어느 층인가 — Cross-cutting Concern

여기서 독자가 혼란을 느끼는 지점이 있다.

“그럼 Skill-based Prompt Engineering 은 Prompt 층의 기법인가? 아니면 Context 층? 둘 다?”

스킬 하나를 만들 때 실제로 무슨 일이 벌어지는지 해부해보자.

스킬 제작 활동 해당 층
guides/qa.md 의 지시문 작성 (답변 구조·톤) Prompt
guides/qa.md 의 Step 1~5 검색 절차 설계 Context
AGENT_GUIDE.md 라우팅 테이블에 /qa 행 추가 Context
.claude/commands/qa.md / .gemini/commands/qa.toml 등록 Harness (CLI 호출 규약)
스킬 메타데이터 (description) 작성 Context (라우팅 결정 정보)

한 기법이 세 층 모두를 건드린다. 이 현상을 정확히 지칭하는 소프트웨어 공학 용어가 있다.

6.1 Cross-cutting Concern (횡단 관심사)

소프트웨어 공학에서 여러 계층에 걸쳐 구현되는 관심사를 cross-cutting concern 이라 한다. 전통적 예시:

Presentation  │  Business  │  Data
──────────────┼────────────┼──────
   로깅 ──────┼──── 로깅 ──┼── 로깅     ← cross-cutting
   보안 ──────┼──── 보안 ──┼── 보안     ← cross-cutting
   트랜잭션 ──┼─── 트랜잭션 ┼─ 트랜잭션  ← cross-cutting

로깅이 presentation 층 “만의” 관심사도, business 층 “만의” 관심사도 아니듯이. 어느 한 층에 깔끔히 속하지 않고 모든 층에 걸쳐 일관되게 구현돼야 한다.

LLM 엔지니어링의 3 층 (Prompt / Context / Harness) 에 같은 구조를 적용하면:

Prompt  │  Context  │  Harness
────────┼───────────┼─────────
 Skill-based PE ────┼──────────  ← cross-cutting
 ReAct ─────────────┼──────────  ← cross-cutting (Prompt + Harness)
 MCP ───────────────┼──────────  ← cross-cutting (Context + Harness)
 Memory system ─────┼──────────  ← cross-cutting (Context + Harness)

6.2 정의

Skill-based Prompt Engineering 은 Prompt·Context·Harness 3 층을 횡단하는 cross-cutting implementation pattern 이다.

이름에 “Prompt” 가 있어서 Prompt 층 안의 기법으로 보이지만, 실제로는 여러 층의 설계 결정을 하나의 패턴으로 묶은 것이다. 스킬 한 개 만들 때 Prompt·Context·Harness 모두에 작업이 발생하는 이유가 여기 있다.

6.3 왜 이 용어가 중요한가

“Cross-cutting 이다” 라고 명명하면 세 가지 혼동이 한 번에 풀린다.

  1. “Skill-based PE 가 Prompt + Context + Harness 를 모두 포함하나?” — 아니다. 포함 관계가 아니라 관통 관계다. 로깅이 presentation 을 “포함” 하지 않듯이
  2. “그럼 Skill-based PE 를 공부하면 세 층을 다 알게 되나?” — 아니다. 각 층의 관심사 중 일부 만 건드릴 뿐, 각 층 전체를 다루지 않는다
  3. “어느 층에서 공부해야 하나?” — 세 층의 기초 개념을 먼저 잡은 뒤, cross-cutting 관점에서 통합. 개별 층을 건너뛰면 안 된다

7 LLM 엔지니어링의 다른 Cross-cutting Concern 예시

Skill-based PE 외에도 3 층을 횡단하는 기법이 여럿 있다.

기법 관여하는 층 횡단하는 이유
Skill-based PE Prompt + Context + Harness 스킬 파일 내용 (Prompt), 로딩 정책 (Context), CLI 호출 규약 (Harness)
ReAct Prompt + Harness 추론·행동 패턴 (Prompt), tool loop (Harness)
MCP (Model Context Protocol) Context + Harness 도구 스키마 주입 (Context), 프로토콜 런타임 (Harness)
Memory system Context + Harness 저장은 Harness, 활용 전략은 Context
Tool use Context + Harness 도구 스키마 (Context), 실행 loop (Harness)
RAG Context (거의 전부) 드물게 Cross-cutting — 대개 Context 단일
Auto-compaction Harness 단일 층 — Cross-cutting 아님
Few-shot Prompt 단일 층 — Cross-cutting 아님

판단 기준: 어느 한 층만 손봐서 구현이 끝나면 단일-층 기법, 둘 이상 층을 동시에 건드려야 구현이 완결되면 cross-cutting.

이 분류는 기법의 학습 순서에도 영향을 준다. 단일-층 기법은 해당 층 기초를 배운 뒤 바로 접근 가능하지만, cross-cutting 은 관여하는 모든 층의 기초를 먼저 잡아야 이해된다.

8 아키텍트 vs 아키텍처 — 명명의 구분

마지막으로 정리할 구분이 있다.

아키텍트 = 설계자 (사람, 의사결정자)
아키텍처 = 그 설계자가 내린 결정이 만든 구조물

이 프로젝트에서:

  • 아키텍트 = 나 (프로젝트 설계자)
  • 아키텍처 = AGENT_GUIDE 체계 전체

8.1 이 프로젝트의 아키텍처 구성

Architecture: AGENT_GUIDE 체계
│
├── [Harness 선택 결정]          ← 설계자가 선택, 구현은 차용
│   "Claude Code + Gemini CLI 병용"
│
├── [Context 설계]               ← 설계자가 직접 설계
│   ├── CLAUDE.md                   (Claude Code 진입점)
│   ├── GEMINI.md                   (Gemini CLI 진입점)
│   ├── AGENT_GUIDE.md              (라우팅 테이블)
│   ├── guides/AGENT_GUIDE_CORE.md  (항상-온 공통 규칙, CP-1~3)
│   ├── guides/info-search.md       (3-Layer 병렬 탐색)
│   ├── guides/common-mistakes.md   (실패 패턴 누적)
│   └── 절대 규칙 5 개 중복 배치 전략
│
├── [Prompt 설계]                ← 설계자가 직접 설계
│   ├── guides/write-post.md        (/write 스킬)
│   ├── guides/retrofit-post.md     (/fix 스킬)
│   ├── guides/writing-tutor.md     (/writing 스킬)
│   ├── guides/writing-rubric-lv{N}.md  (루브릭)
│   ├── guides/sql-tutor.md         (/sql 스킬)
│   ├── ...                          (총 12 skill 가이드)
│   └── docs/blog/posts/*/GUIDE.md  (카테고리별 스타일)
│
└── [Cross-cutting Pattern]      ← 설계자가 구조로 채택
    Skill-based PE — 위 3 층을 관통하는 구현 패턴
    .claude/commands/*.md  +  .gemini/commands/*.toml

8.2 아키텍트의 역할

  • “Claude Code + Gemini CLI 를 병용한다” 는 Harness 선택 결정
  • “절대 규칙을 세 파일에 중복 배치해 압축을 방어한다” 는 Context 설계 결정
  • “한다 체를 강제하고 수동 번호를 금지한다” 는 Prompt 설계 결정
  • “새 스킬은 .claude/commands/*.md + .gemini/commands/*.toml 쌍으로 추가한다” 는 Cross-cutting 규약 결정

이 결정들이 누적돼 아키텍처라는 구조물이 된다.

8.3 아키텍처의 정의

아키텍처는 파일 구조·라우팅 규칙·Phase 프로토콜·중복 배치 전략·스킬 시스템 등이 합쳐진 체계 다.

아키텍트가 바뀌면 (예: 다른 설계자가 이 프로젝트를 맡으면) 아키텍처가 바뀔 수 있다. 반대로 아키텍처가 문서화돼 있으면 (이 글처럼) 새 아키텍트가 그 체계를 유지·확장할 수 있다. 이게 아키텍처 문서화 의 가치다.

9 왜 이 해부가 중요한가

이런 해부를 왜 하나.

9.1 1. 유지보수 판단이 쉬워진다

“CP-3 를 제거하자” 는 제안이 오면:

  • 해부 없이: “CP-3 가 뭔데? 언제 도입됐지?” 에서 시작
  • 해부 있으면: “CP-3 는 Context 층의 정보 보존 전략이다. 제거하면 auto-compaction 후 Self-Check 가 누락될 위험이 커진다. 대안으로 다른 방어 기제가 필요한가?” 로 즉시 판단

유지보수 결정이 층위 관점에서 평가되면 체계 일관성이 유지된다.

9.2 2. 확장 방향이 예측 가능해진다

“MCP 지원 추가” 같은 확장이 오면:

  • MCP 는 Context + Harness 의 cross-cutting 이다 (위 표 참조)
  • 이 프로젝트는 Harness 를 차용 한다 → MCP 의 Harness 쪽은 Claude Code / Gemini CLI 의 MCP 구현에 의존
  • Context 쪽만 우리가 설계 — MCP 서버 목록, 스킬-서버 매핑 규약 추가

확장의 범위와 책임 경계가 명확해진다.

9.3 3. 다른 프로젝트에 이식 가능한 원리가 추출된다

“이 프로젝트 구조가 왜 잘 작동하나” 의 답을 구체 파일명 없이 서술할 수 있다:

  • Prompt + Context 는 직접 설계
  • Harness 는 성숙한 CLI 차용
  • Harness-aware 방어 기제 (중복 배치, CP 체크포인트) 삽입
  • 새 기능은 cross-cutting 스킬 패턴으로 추가

이 네 원리만 가져가면 다른 프로젝트도 유사한 품질의 AGENT_GUIDE 체계를 구축할 수 있다.

10 결론

이 블로그 프로젝트의 AGENT_GUIDE 체계는 Prompt + Context 두 층을 직접 설계하고 Harness 는 차용하는 구조다. 표면적으로 “skill-based prompt engineering” 이라 부르지만, 실제로는 Context 층 설계가 비중의 절반 이상이며, Skill-based PE 자체는 cross-cutting concern 으로 세 층을 관통한다.

핵심 용어 정리:

  • Harness-aware Context Engineering — 하네스를 만들지 않지만 그 한계를 의식해 방어적으로 Context 를 설계
  • Cross-cutting concern — 하나의 기법이 여러 층을 관통하는 구현 패턴 (Skill-based PE, ReAct, MCP, Memory system 등)
  • 아키텍트 vs 아키텍처 — 설계자 (사람) vs 설계 결과물 (구조)

이 구분은 유지보수·확장·이식 판단의 기초가 된다. “이 규칙을 고치면 뭐가 깨지나” 가 층위 관점 에서 답 가능해지고, “이 기능을 추가하려면 어디를 건드리나” 가 cross-cutting 매핑 으로 답 가능해진다.

11 관련 주제

전제 개념

스킬 시스템

시스템 프롬프트 설계

12 참고문헌

12.1 Cross-cutting concern 개념 (소프트웨어 공학)

  • Kiczales, G. et al. (1997). Aspect-Oriented Programming. ECOOP.
  • Laddad, R. (2009). AspectJ in Action: Enterprise AOP with Spring Applications. Manning.

12.2 3 층 프레임 (LLM 엔지니어링)

  • Anthropic. (2025). Claude Code Documentation. https://docs.claude.com/claude-code
  • Karpathy, A. (2024). Context Engineering Threads. X/Twitter.
  • Anthropic. (2024). Model Context Protocol (MCP) Specification. https://modelcontextprotocol.io

12.3 관련 기법

  • Yao, S. et al. (2022). ReAct: Synergizing Reasoning and Acting in Language Models. arXiv:2210.03629.
  • Packer, C. et al. (2023). MemGPT: Towards LLMs as Operating Systems. arXiv:2310.08560.

Subscribe

Enjoy this blog? Get notified of new posts by email: