지도는 영토가 아니다 — 탐험가(Explorer)와 구축자(Builder) 사이의 의존성 인지 에이전트(Dep-Aware Agent)

지능의 문제

정찰팀이 월요일에 영토를 지도화합니다. 그들은 진입 지점, 구조적 레이아웃, 활성 시스템 등 모든 것을 포함한 철저한 보고서를 작성합니다. 보고서는 정확합니다. 그들은 자신의 임무를 잘 수행했습니다.

목요일, 타격대가 그 보고서를 가지고 투입됩니다.

아무도 확인하지 않은 사실: 화요일에 경비 교대 근무가 바뀌었습니다. 수요일에는 누군가 동쪽 문을 용접하여 폐쇄했습니다. 보고서는 여전히 90% 정확합니다. 문제는 나머지 10%에서 발생합니다.

이것이 모든 정보 기관, 수술팀, 그리고 결국 모든 엔지니어링 조직이 직면하는 운영상의 격차(operational gap)입니다. 즉, 분석이 실행되는 시점과 구현이 시작되는 시점 사이의 거리는 0이 아닙니다. 그 격차 사이에서 상황은 변합니다. 아무도 이를 공지하지 않습니다. 그것이 중요한 변화처럼 느껴지지도 않습니다.

결과가 나타나기 전까지는 말입니다.

탐험가(Explorer)의 지도는 노후화됩니다

표준적인 하네스(harness) 워크플로우 — 리드(Lead) → 탐험가(Explorer) → 구축자(Builder) → 검토자(Reviewer) — 는 적절한 문제 세트를 해결합니다. 탐험가는 구축자가 눈먼 상태로 들어가지 않도록 코드베이스를 지도화합니다. 구축자는 추측이 아닌 프로젝트의 실제 모습을 바탕으로 구현을 진행합니다. 검토자는 모든 것이 종료되기 전에 검증합니다.

하지만 탐험가는 스냅샷(snapshot)을 생성합니다. 그것은 실행된 시점에는 정확합니다. 탐험가가 분석한 코드베이스와 구축자가 작성을 시작하는 코드베이스가 동일하다는 것은 두 세션 사이에 아무런 변화가 없었을 때만 보장됩니다.

실제로는 거의 항상 무언가가 변합니다. 의존성(dependency)이 업데이트됩니다. 설정(config)이 바뀝니다. 다음 세션이 시작되기 전에 누군가 npm install을 실행합니다. 아무도 이를 공지하지 않습니다. 중요하게 느껴지지도 않습니다.

그러다 drizzle-orm이 0.36에서 0.45로 — 메이저 업데이트(major bump) — 변경되면, 구축자는 해당 릴리스에서 변경된 쿼리 패턴을 사용하여 구현을 진행합니다. 탐험가의 분석은 정확했습니다. 계획은 견고했습니다. 코드는 거의 작동합니다. 아무도 거짓말을 하지 않았습니다. 아무도 단계를 놓치지 않았습니다. 워크플로우는 깔끔하게 실행되었습니다. 단지 단계 사이에 지형이 변했고 아무도 확인하지 않았을 뿐입니다.

그것이 바로 v1.6.4가 해결하기 위해 구축된 실패 모드(failure mode)입니다.

특정 문제를 위한 다섯 번째 역할

표준 하네스(harness) 워크플로우에는 네 가지 역할이 있습니다: Lead (조율), Explorer (읽기 및 매핑), Builder (구현), Reviewer (검증). 각 역할은 정의된 권한 범위(permission scope)를 가집니다. 각 역할은 체인 내에서 명확한 위치를 점유합니다.

Consultant는 다섯 번째 역할이지만, 표준 체인의 일부가 아니라 조건부로 작동합니다. Lead는 상황이 정당화될 때만 Consultant를 호출합니다:

• deps.check가 significant: true를 반환할 때
• 작업이 package.json, 의존성(dependencies), 또는 설정 파일(config files)을 명시적으로 다룰 때
• .harness/deps-lock.json이 아직 존재하지 않을 때 (첫 번째 작업이며 기준점(baseline)이 없는 경우)

의존성이 안정적인 일상적인 기능 작업(routine feature work) 시 Consultant는 결코 등장하지 않습니다. 체인은 네 가지 역할로 유지됩니다. Consultant는 그 오버헤드(overhead)가 정당화될 때만 추가적인 비용을 발생시킵니다.

이를 가능하게 하는 MCP 도구들

v1.6.4에는 두 가지 새로운 도구가 포함되어 있으며, 두 도구 모두 Consultant 역할 전용입니다. 다른 에이전트는 이를 호출할 수 없습니다.

deps.snapshot

package.json의 현재 상태(dependencies 및 devDependencies 모두 포함)를 캡처하여 타임스탬프와 함께 .harness/deps-lock.json에 기록합니다. 이것이 기준점(baseline)이 됩니다. 새로운 프로젝트에서 Consultant가 처음 호출될 때 자동으로 실행됩니다.

{
  "capturedAt": "2026-06-05T10:23:00.000Z",
  "message": "Snapshot saved to .harness/deps-lock.json"
...

deps.check

저장된 기준점과 현재 package.json을 비교(diff)합니다. 다음과 같은 구조화된 결과를 반환합니다:

{
  "significant": true,
  "added": ["zod@3.24.0"],
...

significant: true는 Consultant의 전체 검토가 필요한 변화가 발생했음을 의미합니다. 사소한 패치(minor patches)나 변화가 없는 경우에는 significant: false를 반환하며, 이 경우 Lead는 Consultant를 완전히 건너뛸 수 있습니다.

Consultant가 실제로 생성하는 것

Consultant의 출력물은 패키지 목록이 아닙니다. 그것은 Builder가 코드 한 줄을 작성하기 전에 읽게 되는 구조화된 권고 사항(structured advisory)입니다.

actions.write를 사용하여, Consultant는 작업의 액션 히스토리(action history)에 네 가지 섹션을 기록합니다:

준수해야 할 패턴 (Patterns to follow) — Builder가 반드시 존중해야 하는 코드베이스 내의 기존 컨벤션 (conventions). 일반적인 조언이 아닙니다. Explorer가 발견한 내용에 특화된 정보입니다.

리스크 및 경고 (Risks & warnings) — 현재의 변경 세트(change set)를 고려할 때 잘못될 수 있는 부분. 대규모 ORM 업데이트는 쿼리 패턴 (query patterns)이 변경되었을 수 있음을 의미합니다. 새로운 검증 라이브러리 (validation library)는 기존의 폼 처리 (form handling) 패턴이 이제 일관되지 않음을 의미합니다. 이는 가설이 아니라 실제 디프 (diff)에서 도출된 내용입니다.

모범 사례 (Best practices) — 프로젝트의 현재 상태를 고려할 때 이 작업에 대한 핵심 고려 사항.

의존성 노트 (Dependency notes) — 작업이 package.json을 건드릴 때만 작성합니다. 무엇이 변경되었는지, 파괴적 변경 사항 (breaking changes)은 무엇인지, 그리고 에이전트 스킬 파일 (agent skill files)을 갱신해야 하는지 여부를 포함합니다.

Builder는 작업을 시작하기 전 actions.get(taskId)를 통해 이 모든 내용을 읽습니다. Explorer의 분석과 Consultant의 자문이 결합되어 Builder에게 전체적인 그림을 제공합니다. 즉, 코드베이스가 어떻게 생겼는지뿐만 아니라 무엇이 변경되었고 무엇을 주의해야 하는지까지 알려줍니다.

자문 전용 제약 조건은 우연이 아닙니다

Consultant는 Read 및 Bash 권한(파일을 읽고 안전한 진단 명령을 실행하기 위함)을 가집니다. 쓰기 권한 (write access)은 없습니다. 파일을 생성할 수 없습니다. 소스 코드를 수정할 수 없습니다. 데이터베이스를 건드릴 수 없습니다.

이는 의도적인 설계이며, 매우 중요합니다.

쓰기 권한까지 가진 자문 역할은

"Docs/README 분석: [docs/, README.md 또는 기타 문서 파일이 이 변경 사항을 반영해야 하는지 여부와 구체적으로 무엇을 반영해야 하는지 기술 — 또는 짧은 이유와 함께 '업데이트 필요 없음'이라고 명시적으로 상태를 밝힘]"

이것은 모든 작업에 포함되는 마지막 수락 기준 (acceptance criterion)이며, 리뷰어 (Reviewer)에 의해 강제됩니다. 만약 이 항목이 누락되면, 리뷰어는 다음과 같이 차단합니다: "필수 docs/README 분석 기준이 누락되었습니다. 빌더 (Builder)가 진행하기 전에 리드 (Lead)가 이를 추가해야 합니다." 만약 항목은 존재하지만 빌더의 작업 요약 (action summary)에서 이에 대해 언급이 없다면, 리뷰어는 다음과 같이 차단합니다: "Docs 분석 기준은 존재하지만 문서화되지 않았습니다."

그 결과, 모든 개별 작업에 대해 명시적인 문서화 책임 (documentation accountability)이 부여됩니다. 이는 정책 문서로서도 아니고, 아무도 읽지 않는 CONTRIBUTING.md의 가이드라인으로서도 아니며, 워크플로우 (workflow) 끝에 위치한 엄격한 게이트 (hard gate)로서 작동합니다.

업데이트된 워크플로우

Lead
  ↓  (항상)
Explorer
...

대부분의 작업에 대해 체인은 여전히 Lead → Explorer → Builder → Reviewer 순서로 유지됩니다. 컨설턴트 (Consultant)는 그 자리를 확보했을 때 투입됩니다. 컨설턴트가 투입되면, 빌더는 코드베이스 (codebase)가 어떻게 생겼는지뿐만 아니라, 무엇이 변했는지와 그것이 무엇을 의미하는지를 포괄하는 브리핑 (brief)을 받게 됩니다.

v1.6.4 가져오기

npx @cardor/agent-harness-kit init

이미 프로젝트에 하네스 (harness)가 있다면, 업데이트된 에이전트 (agent) 파일들을 동기화하세요:

ahk build

consultant.md 에이전트 파일은 귀하의 프로바이더 (provider) 설정에 따라 .claude/agents/, .opencode/agents/, 또는 .codex/agents/에 추가됩니다. 두 개의 새로운 MCP 도구 (tools)는 자동으로 등록됩니다. 필수 문서 기준은 업데이트된 리드 (Lead)의 지침 (instructions)에 내장되어 있습니다.

Built with agent-harness-kit — 구조화된 멀티 에이전트 (multi-agent) AI 워크플로우를 위한 프로바이더 불가지론적 (provider-agnostic) 스캐폴딩 (scaffolding).