"하네스 부록 E1 — 용어집과 치트시트: AGENTS.md부터 handoff까지 한 번에 정리"

-

하네스 엔지니어링 글을 읽다 보면 개념은 알겠는데 용어가 서로 겹쳐 보일 때가 많다. AGENTS.md와 CLAUDE.md는 어떻게 다르고, handoff와 memory는 어디서 갈리며, MCP와 tool은 같은 말이 아닌데 무엇이 다른가. 이 글은 시리즈 전반에 등장한 핵심 용어를 실무 정의와 빠른 판단표로 다시 정리한 companion appendix다.

핵심 요약

  • 용어를 외우는 목적은 정의 암기가 아니라 운영 경계 구분이다.
  • 비슷해 보이는 단어도 "누가 읽는가", "언제 적용되는가", "무엇을 통제하는가"로 구분하면 헷갈림이 줄어든다.
  • 좋은 하네스는 긴 설명보다 짧은 지시 표면, 좁은 도구 표면, 명시적 검증 표면, 복원 가능한 상태 표면으로 정리된다.
  • handoff는 장기 작업 복원용이고, memory는 반복 재사용용이라는 구분이 특히 중요하다.
  • 아래 치트시트만 기억해도 시리즈 A부터 E까지 대부분의 글을 더 빠르게 읽을 수 있다.

1. 먼저 큰 지도부터: 하네스는 어떤 층으로 나뉘는가

시리즈 전체에서 반복해서 등장한 개념은 사실 몇 개의 층으로 묶인다.

층 핵심 질문 대표 예
지시 표면 에이전트는 어떤 규칙으로 시작하는가 AGENTS.md, CLAUDE.md, system instruction
문맥 표면 지금 무엇을 읽고 무엇을 생략하는가 사용자 요청, 참조 문서, tool result
도구 표면 무엇을 실행할 수 있는가 shell, file read/write, web, MCP
검증 표면 결과가 틀렸을 때 무엇이 먼저 잡는가 test, hook, eval, review
지속성 표면 세션이 끝난 뒤 무엇이 남는가 handoff, sessions, docs, long-term memory
운영 표면 위험과 비용을 어떻게 통제하는가 permissions, sandbox, approval, audit

용어를 개별 단어로 보면 복잡하지만, 이 여섯 층에 배치하면 대부분의 위치가 정리된다.

2. 핵심 용어집 15선

1. Harness

  • 정의: 모델이 일하는 전체 작업 환경과 운영 구조
  • 구분 포인트: 모델 자체가 아니라 모델 바깥의 지시, 도구, 검증, 메모리, 권한까지 포함한다

2. Agent

  • 정의: 모델이 지시와 도구를 받아 작업 루프로 행동하는 실행 주체
  • 구분 포인트: 단순 챗봇보다 넓고, tool call과 state transition을 포함한다

3. AGENTS.md

  • 정의: 저장소 단위의 공통 규칙과 경계를 담는 최상위 지시 파일
  • 구분 포인트: 프로젝트 경계, 금지 영역, 역할 정책처럼 공유 규칙에 강하다

4. CLAUDE.md

  • 정의: Claude 계열 작업에서 런타임 행동 원칙을 주입하는 지시 파일
  • 구분 포인트: 세션 흐름, 작업 절차, 세부 행동 규칙처럼 실행 지침에 강하다

5. Skill

  • 정의: 반복 절차를 별도 문서나 호출 단위로 분리한 실행 매뉴얼
  • 구분 포인트: 자주 반복되는 과정을 본문 지시에서 떼어 내어 짧게 재사용한다

6. Tool

  • 정의: 에이전트가 호출할 수 있는 구체적 행동 수단
  • 구분 포인트: 파일 읽기, 셸 실행, 검색처럼 직접 행동을 유발한다

7. MCP

  • 정의: 외부 도구와 데이터 시스템을 연결하는 프로토콜 또는 표준 인터페이스 층
  • 구분 포인트: 개별 tool과 같지 않다. MCP는 연결 방식, tool은 실제 행동 단위다

8. Context window

  • 정의: 한 번의 실행에서 모델이 실제로 보고 판단하는 입력 예산
  • 구분 포인트: "무엇이 저장됐는가"와 다르다. 지금 무엇이 로드됐는가의 문제다

9. Handoff

  • 정의: 장시간 작업을 다음 세션이나 다음 실행자에게 넘기기 위한 구조화된 인계 기록
  • 구분 포인트: 반복 재사용보다 작업 재개에 초점이 있다

10. Memory

  • 정의: 세션 밖에 보존되는 재사용 가능한 지식 또는 상태 계층
  • 구분 포인트: handoff보다 넓다. 장기 지식, 규칙, 선호, 패턴을 포함할 수 있다

11. Eval

  • 정의: 결과물이나 행동 품질을 점검하는 자동 또는 반자동 평가 구조
  • 구분 포인트: 정답 검사, 루브릭 검사, 회귀 검사처럼 여러 형식이 있다

12. Hook

  • 정의: 특정 이벤트 전후에 강제로 실행되는 정책 또는 검증 코드
  • 구분 포인트: "권고 문장"이 아니라 실행 강제 장치다

13. Sandbox

  • 정의: 파일, 명령, 네트워크 같은 행동 범위를 제한하는 격리 실행 환경
  • 구분 포인트: 안전을 위한 것인 동시에 실수의 반경을 줄이는 운영 장치다

14. Approval policy

  • 정의: 어떤 행동은 자동 허용하고, 어떤 행동은 확인하거나 차단할지 정하는 규칙
  • 구분 포인트: 읽기/수정/실행/외부 전송을 같은 위험도로 보지 않는다

15. Memory ownership

  • 정의: 에이전트의 장기 기억을 누가 저장하고, 이동하고, 삭제하고, 감사할 수 있는지에 대한 통제권
  • 구분 포인트: 저장 기능이 아니라 운영권과 이식성의 문제다

3. 가장 자주 헷갈리는 쌍 비교

헷갈리는 쌍 이렇게 구분하면 된다
AGENTS.md vs CLAUDE.md 전자는 저장소 공통 경계, 후자는 런타임 작업 행동 규칙
prompt vs context prompt는 지시 문장, context는 지시를 포함해 실제로 보여 준 전체 재료
tool vs MCP tool은 행동 단위, MCP는 외부 능력을 연결하는 표준 층
handoff vs memory handoff는 재개용, memory는 재사용용
eval vs review eval은 반복 가능한 평가 구조, review는 사람 또는 별도 평가자의 해석적 판단
hook vs guideline hook은 강제, guideline은 권고
sandbox vs permission sandbox는 실행 환경 제한, permission은 허용 정책의 범위 정의

4. 실무 치트시트: 문서와 규칙은 어디에 둬야 하나

아래 표는 "무엇을 어디에 둬야 하는가"를 빠르게 판단하기 위한 것이다.

넣을 내용 기본 위치 이유
프로젝트 전체 금지선 AGENTS.md 모두가 공유해야 하는 경계이기 때문
특정 도구 사용 절차 skill 또는 참조 문서 지시 본문을 비대하게 만들지 않기 위해
이번 세션의 다음 행동 handoff 또는 session note 다음 실행자가 바로 재개해야 하기 때문
장기 재사용 규칙 docs/, tasks/lessons.md, memory store 반복적으로 다시 써야 하기 때문
절대 위반하면 안 되는 검사 hook, validator, test 문장 권고보다 강제가 필요하기 때문

5. 빠른 판단표: 지금 문제는 어느 층의 실패인가

증상 먼저 의심할 층 첫 점검 질문
같은 요청인데 답 형식이 자꾸 흔들린다 지시 표면 출력 계약이 고정돼 있는가
엉뚱한 도구를 고른다 도구 표면 도구 이름과 설명이 구분 가능한가
길게 일하다가 맥락을 잃는다 지속성 표면 handoff artifact가 남아 있는가
위험한 파일이나 외부 작업을 건드린다 운영 표면 권한 경계와 승인 정책이 분리됐는가
겉보기엔 그럴듯한데 자주 틀린다 검증 표면 빠른 deterministic check가 앞단에 있는가
같은 실수를 반복한다 메모리/평가 표면 실패 사례가 회귀셋이나 lessons로 승격됐는가

6. 부록형 치트시트: 시리즈별 핵심 한 줄

시리즈 기억할 한 줄
A 기초 모델보다 중요한 것은 모델이 일하는 작업대다
B 구현 OpenAI와 Claude는 기능보다 운영 철학의 차이가 크다
C 운영 평가, handoff, 안전장치, 메모리가 품질의 핵심이다
D 전략 좋은 하네스는 기능 모음이 아니라 반복 가능한 패턴과 결정의 묶음이다
E 부록 용어, 출처, 워크시트 같은 companion asset이 실전 적용 속도를 높인다

7. 이 저장소 기준으로 읽으면 더 잘 보이는 대응 관계

개념 저장소 대응 예시
instruction surface AGENTS.md
memory index docs/memory-map.md
long-running handoff tasks/handoffs/, tasks/sessions/
reusable operating rules tasks/lessons.md
bounded publishing rule 외부 게시 전 사용자 확인 원칙

이런 대응 표가 중요한 이유는 하네스 용어를 추상 개념으로만 남기지 않고, 실제 파일과 운영 경계로 번역해 주기 때문이다.

8. 흔한 오해

용어를 많이 알면 하네스를 이해한 것이라 생각한다

아니다. 중요한 것은 각 용어가 어느 실패를 줄이는지 이해하는 것이다.

memory가 handoff를 대체한다고 생각한다

둘은 겹치지만 목적이 다르다. 장시간 작업에서는 대개 handoff가 먼저다.

MCP를 붙이면 자동으로 능력이 커진다고 생각한다

연결이 늘어도 표면이 복잡해지면 오히려 도구 선택 품질이 떨어질 수 있다.

문서에 써 두면 강제된다고 생각한다

반드시 막아야 하는 것은 hook, validator, permission 쪽으로 내려야 한다.

9. 마지막 체크: 이 다섯 줄만 기억해도 된다

  1. AGENTS.md는 공통 경계, CLAUDE.md는 런타임 행동 규칙이다.
  2. tool은 행동 단위, MCP는 연결 표준이다.
  3. handoff는 재개용, memory는 재사용용이다.
  4. hook은 강제, guideline은 권고다.
  5. 메모리 소유권은 기능이 아니라 운영 통제권이다.

참고 자료

  • AGENTS.md
  • docs/blog_series_하네스엔지니어링_총괄_design.md
  • docs/memory-map.md
  • sources/260518_하네스엔지니어링_15장_블로그활용노트.md
  • drafts/blog/260519_하네스시리즈A03_컨텍스트설계와지시파일_블로그.md
  • drafts/blog/260519_Claude하네스B02_CLAUDEmd_Skills_Hooks_Permissions_블로그.md
  • drafts/blog/260519_하네스시리즈C02_장시간에이전트운영_블로그.md
  • drafts/blog/260519_하네스시리즈C04_메모리소유권_블로그.md

이 글은 부록 컴패니언 시리즈의 E1 편입니다. 다음 편: 출처 지도와 검증법 — 무엇을 1차 자료로 보고, 무엇을 활용 노트로만 써야 하는가.

시리즈 전체 안내: 하네스 엔지니어링 시리즈 안내

댓글

댓글 쓰기

이 블로그의 인기 게시물

"LLM 핵심 학습 (1/6) — 기본: 토큰화·임베딩·어텐션·위치 인코딩"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/6 파인튜닝 → 트랜스포머 한 블록의 데이터 흐름을 문자열 → 토큰 → 임베딩 → 어텐션 → 출력 표현 까지 손으로 풀어 본다. 이번 편이 끝나면 "왜 \(\sqrt{d_k}\)로 나누는가", "RoPE는 무엇을 회전시키는가", "한국어가 영어보다 토큰이 많은 까닭은 무엇인가"가 한 줄로 설명될 수 있다. 0. 학습 목표 이 편을 마치면 다음을 직접 할 수 있다. BPE 토크나이저 가 어휘를 어떻게 학습하고 새 문자열을 어떻게 자르는지 종이 위에서 시뮬레이션한다. 임베딩 행렬 의 모양과 초기화, weight tying의 의미를 한 줄로 설명한다. Scaled Dot-Product Attention 의 식을 차원 단위로 추적하고 PyTorch 30줄로 재현한다. Multi-Head Attention 이 한 헤드와 비교해 무엇이 다른지, 헤드 수가 늘면 어디가 비싸지는지 답한다. Sinusoidal·RoPE·ALiBi 세 위치 인코딩의 식과 외삽 성질을 구분한다. 컨텍스트 확장이 왜 \(O(N^2)\)인지, "Lost in the Middle"이 왜 발생하는지 설명한다. 1. 핵심 요약 트랜스포머의 입력은 문자열 이 아니라 정수 ID 시퀀스 다. 토크나이저가 문자열 → ID로 자른다. 임베딩은 정수 ID를 \(d\)차원 벡터로 lookup하는 학습 가능한 테이블이다. Self-Attention은 \(\text{softmax}(QK^\top / \sqrt{d_k}) V\) 한 줄이 핵심이고, 멀티헤드는 같은 연산을 여러 부분 공간에서 병렬화한 것이다. 위치 정보는 임베딩에 직접 더하거나(Sinusoidal), Q·K에 회전을 가하거나(RoPE), 어텐션 스코어에 거리 패널티를 더해서(ALiBi) 주입한다. 컨텍스트 길이 \(N\)에 대해 표준 어텐션은 \(O(N^2)\) 비용을 갖고, 긴 컨텍스트에서는 중간 위...
Read more »

"LLM 핵심 학습 (2/6) — 파인튜닝: LoRA·QLoRA·증류·Adapter"

-
이미지
← 1/6 기본 📚 시리즈 목차 3/6 디코딩과 생성 → 사전학습된 LLM을 내 데이터 에 적응시키는 방법을 비용·메모리·일반화 관점에서 정리한다. Full FT의 한계 → Adapter → LoRA → QLoRA → Distillation 순으로 같은 그림을 점점 확대해 본다. 0. 학습 목표 Full fine-tuning의 메모리 병목을 옵티마이저 상태·그래디언트·가중치·활성화 의 4분할로 설명한다. Adapter(Houlsby 2019)와 LoRA(Hu 2021)의 식 차이를 한 줄로 적는다. LoRA의 \(A, B\) 행렬이 왜 저랭크 이고, rank \(r\) 선택이 무엇을 결정하는지 답한다. QLoRA(Dettmers 2023)의 NF4·double-quant·paged optimizer를 분리해서 설명한다. Catastrophic Forgetting을 분포 시프트 관점에서 정의하고 완화 기법을 두 개 이상 든다. Hinton 2015의 Knowledge Distillation 식을 손으로 유도한다. 1. 핵심 요약 Full FT는 메모리/디스크/시간 모두 비싸다. 7B 모델 full FT는 V100 8장 + A100 1장으로도 큰 부담이다. PEFT(파라미터 효율 파인튜닝) 일가족은 극히 일부 파라미터만 학습 해 같은 효과를 얻는다. LoRA: \(\Delta W = BA\) (rank \(r \ll \min(d_{\text{in}}, d_{\text{out}})\))로 가중치 업데이트를 저랭크 분해. QLoRA: 베이스 모델을 4-bit(NF4)로 양자화한 채 LoRA만 풀-정밀(BF16)으로 학습. Catastrophic Forgetting: 새 분포에 적응하느라 이전 능력이 무너지는 현상. PEFT 자체가 부분 완화책. Distillation: 큰 교사 모델의 soft target 을 학습 신호로 써서 작은 학생 모델 을 만든다. 2. 직관: 왜 사전학습만으로는 부족한가 사전학습은 일반...
Read more »

"ML 기초 학습 (1/9) — 머신러닝과 sklearn: 학습의 좌표계"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/9 이웃 알고리즘 → 이 시리즈는 신경망과 로컬 LLM으로 가기 전에 손에 익혀 둬야 할 머신러닝 기초 9편이다. 1편은 모든 ML 코드가 공유하는 공통 문법 을 잡는 데 쓴다. sklearn은 그 문법을 가장 일관되게 보여주는 도구다. 이번 편이 끝나면 어떤 모델을 만나도 fit → predict → score → 평가 흐름이 같다는 것이 손에 잡힌다. 0. 학습 목표 이 편을 마치면 다음을 할 수 있어야 한다. 지도학습·비지도학습·강화학습을 한 문장씩 구분해 설명한다. sklearn의 estimator 인터페이스 ( fit , predict , score , transform )를 코드 한 화면 안에서 쓸 수 있다. train/validation/test 분할을 왜 하는지, 어디서 데이터 누수가 생기는지 식과 그림으로 설명한다. 분류·회귀의 핵심 평가 지표(accuracy, precision, recall, F1, MSE, R²)를 정의에서 직접 계산할 수 있다. k-fold 교차검증 을 코드 한 줄로 돌리고, 결과의 평균과 표준편차를 함께 보고할 수 있다. Pipeline 으로 전처리와 모델을 묶어 데이터 누수를 구조적으로 막는 방법을 설명한다. 1. 핵심 요약 머신러닝은 데이터에서 함수 \(f: X \to Y\)를 찾는 작업 이다. 어떤 모델이든 이 본질은 같다. sklearn은 모든 모델을 같은 인터페이스( fit , predict , score )로 통일해, 모델을 바꿀 때 한 줄만 바꾸면 되게 한다. train/val/test 세 분할이 표준이다. 검증으로 하이퍼파라미터를 고르고, 테스트는 마지막에 한 번만 본다. 데이터 누수 (test 정보가 train에 새는 현상)는 ML 입문자가 가장 자주 만드는 실수이며, Pipeline + cross_val_score 조합으로 구조적으로 막을 수 있다. 평가 지표는 문제 유형 (분류/회귀) 과 클래스 불균형...
Read more »