“여러 AI 도구(Claude Code, Cursor, OpenCode, Paseo 등)를 쓸 때 가장 큰 재앙은 도구마다 프롬프트와 규칙을 복사-붙여넣기하는 순간 시작된다. 룰이 파편화되고, 어디선가 수정된 보안 규칙이 다른 툴에는 반영되지 않아 사고가 터진다.”
이를 해결하기 위해 최상위 계정(Account) 단위의 전역 철학부터 **프로젝트(Project)**의 도메인 지식, 그리고 각 **런타임 도구(Adapter)**의 실행 환경까지 단일한 진실 공급원(SSOT)으로 묶어내는 5단계 계층형 하네스(Harness) 아키텍처를 구축했습니다.
1. 5단계 설정 계층: 상속과 오버라이드 (Hierarchy)
모든 AI 에이전트는 독립된 개체로 동작하는 것이 아니라, 명확한 상속 체계 안에서 규칙을 주입받습니다.
① 계정 수준 (~/.agents/)
└─ 전역 코어 원칙, 모델 등급, 위임 규범, 보안 봉인 규칙 (SSOT)
│
▼
② 오케스트레이터 수준 (Paseo)
└─ 에이전트 생성(create_agent), 프로필 라우팅, 백그라운드 감독 정책
│
▼
③ 프로젝트 수준 (AGENTS.md, .agents/)
└─ 리포지토리 아키텍처, 도메인 제약, 테스트/린트 정책, 디렉토리 구조
│
▼
④ 런타임 어댑터 수준 (~/.claude/CLAUDE.md, adapters/*.md)
└─ 도구별 고유 인터페이스 매핑, 훅(Hooks) 바인딩, CLI 환경설정
│
▼
⑤ 대화 중 사용자 지시
└─ 실시간 턴별 명시 요구 (최우선 순위)거버넌스를 지탱하는 두 가지 핵심 규범
- 하향식 상속과 명시적 오버라이드 (Explicit Override):
- 하위 계층은 상위 계층을 자동으로 상속받습니다.
- 하위에서 상위 규칙을 수정해야 할 때는 반드시
override: <상위문서 §> — 이유를 명시해야만 유효합니다. 표기 없는 모순된 지침은 시스템이 거부합니다.
- 보안 규칙의
[봉인(Sealed)]원칙:- 비밀키 보호, 외부 데이터 반출 금지, 파괴적 작업(DB drop, force push) 차단 등
[봉인]딱지가 붙은 최상위 안전 규칙은 하위 계층에서 강화(더 엄격하게)만 가능합니다. - 이를 완화하거나 해제하는 것은 오직 사용자가 대화 턴에서 건별로 명시 승인할 때만 가능합니다.
- 비밀키 보호, 외부 데이터 반출 금지, 파괴적 작업(DB drop, force push) 차단 등
2. 자동화 빌드 파이프라인: “설정 파일은 사람이 직접 복사하지 않는다”
단일 진실 원천(SSOT)을 유지하기 위해, 인간은 정본(JSON, 마크다운 코어)만 수정하고 나머지는 스크립트가 컴파일하여 각 툴로 주입하는 빌드 파이프라인을 운영합니다.
┌───────────────────────────┐
│ model-tiers.json (SSOT) │
└─────────────┬─────────────┘
│
python3 render-model-tiers.py
│
┌─────────────┴─────────────┐
▼ ▼
[model-tiers.md 표 자동 렌더] [~/.paseo/config.json 프로필 갱신]
│
paseo daemon reload① 모델 티어링 & 프로필 동기화 (render-model-tiers.py)
model-tiers.json에 모델과 등급, 라우팅 규칙(예:gemini메인 ↔deepseek-flash실작업 교차 페어)을 한 줄 등록합니다.- 렌더러 스크립트를 실행하면:
- 사람이 읽는 공식 규범 문서(
model-tiers.md)의 마크다운 표를 자동 렌더링합니다. - 에이전트 데몬인 Paseo의 구동 프로필(
~/.paseo/config.json)을 즉시 재생성하고 데몬을 리로드합니다. --validate및--check옵션으로 런타임 간 불일치가 0건인지 무결성을 검증합니다.
- 사람이 읽는 공식 규범 문서(
② 전역 코어 컴파일 (build-agents.sh)
- 최상위 핵심 원칙인
~/.agents/core.md가 수정되면, 빌드 스크립트가 이를 읽어 Claude Code의 전역 지시자(~/.claude/CLAUDE.md) 및 각 런타임 어댑터 파일 끝에 자동으로 합성·주입합니다. - 어떤 도구(Claude CLI든, Cursor든)를 실행하더라도 항상 동일한
core.md최신본을 머리에 얹고 시작하게 됩니다.
③ 스킬(Skills)의 단일 원본 심링크 체계
- 스킬의 원본은 오직
~/.agents/skills/에만 둡니다. - Claude Code, OpenCode 등 각 도구의 스킬 디렉토리는 이 원본을 가리키는 **심링크(Symlink)**로 연결합니다. 도구별로 사본 폴더를 만들지 않아 스킬 버전이 갈라지는 문제를 원천 차단했습니다.
3. 런타임 어댑터와 안전 훅(Hooks): “얇은 어댑터 패턴”
각 개발 툴 설정(Layer ④)은 무겁게 룰을 갖지 않고, 상위를 임포트하는 **‘얇은 어댑터(Thin Adapter)’**로만 구성됩니다.
[개발 도구 실행: Claude / Cursor / OpenCode]
│
├─► 1. 계정 코어 + 프로젝트 AGENTS.md 로드 (컨텍스트 기반 확립)
│
├─► 2. 도구 전용 도구/명령어 매핑 (런타임 어댑터)
│
└─► 3. 디스패치 및 안전 검사 (Hooks)
├─ 허가되지 않은 최상급 모델 호출 차단/상급 대체
├─ 오케스트레이터 예약 라벨(paseo.*) 변조 차단
└─ 비인가 프로세스 탐색(ps 환경변수 유출 등) 차단- 런타임 중립 훅 (
hooks/):- 에이전트가 다른 서브 에이전트를 dispatch하거나 위험 명령어를 실행할 때, 계정 레벨의 훅 스크립트가 중간에서 페이로드를 가로채 검사합니다.
- 예를 들어, 메인이 상급 세션인데 하위 서브에이전트로 최상급 모델을 임의 호출하려고 하면, 훅이 이를 감지하여 **동일 프로바이더의 상급 모델로 자동 치환(Downgrade/Cap)**하고 1줄 보고를 남깁니다.
4. 실제 개발 워크플로우와의 연계 흐름
개발자가 터미널이나 IDE에서 작업을 시작할 때 이 하네스는 물 흐르듯 작동합니다:
- IDE/터미널 진입:
- 작업 폴더의
AGENTS.md를 읽어 프로젝트 고유의 린트 규칙과 기술 스택을 파악합니다.
- 작업 폴더의
- 작업 착수 전 사전 분류 선언:
- 계정 규칙(
delegation-protocol.md §0)에 따라 에이전트는 무조건 첫 줄에[사전 분류] 작업 유형 | 등급 | 담당 모델 | 직접/위임 | 근거를 사용자에게 선언합니다.
- 계정 규칙(
- 지휘와 분할:
- 대화형 메인 세션(예: Gemini 3.8 Flash)은 큰 작업을 분석하여 비중복 파일 단위(
write_set disjoint)로 슬라이싱합니다.
- 대화형 메인 세션(예: Gemini 3.8 Flash)은 큰 작업을 분석하여 비중복 파일 단위(
- 오케스트레이터를 통한 교차 위임:
- 분할된 단순 반복 구현은 사전에 정의된 라우팅에 따라 데몬(Paseo)을 통해 저비용·초고속 모델(
opencode:일반@deepseek)로 병렬 dispatch됩니다.
- 분할된 단순 반복 구현은 사전에 정의된 라우팅에 따라 데몬(Paseo)을 통해 저비용·초고속 모델(
- 결과 회수 및 사용자 검토:
- 서브 에이전트들은 정해진 결과 형식(
[경로 / 요약 / 검증])만 메인에 반환하고, 메인은 이를 검증하여 최종적으로 사용자 작업 트리에 미커밋(Uncommitted) 변경사항으로 깔끔하게 정리해 올립니다.
- 서브 에이전트들은 정해진 결과 형식(
5. 결론: “도구는 바뀌어도 규칙은 남는다”
새로운 LLM 모델은 매달 쏟아지고, 개발자들이 사용하는 AI 툴도 계속 바뀝니다.
- 어제는 Claude Code만 썼지만,
- 오늘은 Cursor와 OpenCode를 병용하고,
- 내일은 또 다른 CLI 도구가 등장할 수 있습니다.
하지만 이 5단계 계층형 하네스가 구축되어 있으면, 도구가 아무리 바뀌어도 엔지니어링 철학, 보안 정책, 모델 위임 규범은 흔들리지 않습니다. 새로운 도구가 나오면 그저 가장 얇은 어댑터 파일 하나만 연결해주면 즉시 우리 팀의 정예 에이전트로 합류하게 됩니다.