당신의 AI 에이전트가 맹목적으로 탐색하고 있습니다. 여기 그들에게 지도를 주는 방법.

Source: Dev.to

번역할 텍스트가 제공되지 않았습니다. 번역을 원하는 전체 내용을 알려주시면 한국어로 번역해 드리겠습니다.

탐색 세금

멀티‑에이전트 워크플로에서, 각 에이전트는 세션 시작 시 탐색 세금을 납부합니다. 유용한 작업을 수행하기 전에, 먼저 스스로를 정렬해야 합니다:

• 플러그인 시스템은 어디에 존재하나요?
• 어떤 명명 규칙이 적용되나요?
• 어떤 파일이 서브트리‑관리 대상이며 접근이 제한되나요?
• 이미 어떤 결정이 내려졌나요?

작은 코드베이스에서는 이것이 단지 귀찮은 일일 뿐입니다. 하지만 규모가 크거나 여러 에이전트가 동시에 실행되는 경우, 토큰이 사라지는 지점이 바로 여기입니다.

보통의 해결책은 코드베이스를 prose 형태로 설명하는 CLAUDE.md 혹은 AGENTS.md 파일을 두는 것입니다. 이는 도움이 되지만, prose는 수동적입니다. 에이전트는 여전히 설명을 자신이 건드릴 파일에 매핑해야 합니다. 이는 README에 불과하고, 지도는 아닙니다.

실제 인덱스가 무엇인가

인덱스는 문서와 다릅니다.

• 문서는 설명합니다.
• 인덱스는 위치를 찾게 합니다.

우리가 에이전트에게 먼저 제공하고 싶은 것은 플러그인 시스템에 대한 단락이 아니라 구체적인 지도입니다. 예를 들어:

“Public functions go in scripts/plugins/. No underscore prefix. The dispatcher in scripts/k3d-manager loads them lazily. Here are the current plugins and their public functions.”

이것은 탐색이 가능한 형태입니다. 에이전트는 이를 읽고 탐색 없이 바로 올바른 파일과 올바른 패턴으로 이동할 수 있습니다.

Cline을 인덱서로 사용하는 통찰: Cline은 지속적인 메모리를 가지고 있어 세션 간에 코드베이스에 대한 구조화된 이해를 유지할 수 있습니다. 코드를 생성하는 데 사용하는 대신, 우리는 이를 전용 정찰 에이전트로 활용합니다—레포지토리를 읽고 구조화된 지도를 구축하며 최신 상태를 유지하는 역할을 하는 에이전트입니다. 다른 에이전트들은 이 지도를 사용하고 다시 탐색하지 않습니다.

인덱스에 포함된 내용

유용한 코드베이스 인덱스는 세 가지 계층으로 구성됩니다:

구조 — 파일이 위치하고 있는 곳과 그 이유

scripts/
  k3d-manager       # dispatcher — maps function names to plugin files
  lib/              # core libraries; subtree‑managed via lib‑foundation
  plugins/          # lazy‑loaded modules; one file per tool
  tests/            # BATS suites; pure logic, no cluster mocks

계약 — 에이전트가 따라야 할 규칙, 조언이 아닌 사실로 인코딩됨

- New plugins: scripts/plugins/.sh
- Public functions: no underscore prefix
- Private functions: _ prefix
- Privileged commands: _run_command --prefer-sudo, never bare sudo
- if‑count limit: ≤ 8 per function; see etc/agent/if-count-allowlist for exceptions
- Subtree‑managed: scripts/lib/foundation/ — edit upstream only

상태 — 진행 중인 것, 결정된 것, 차단된 것

Active branch: k3d-manager-v0.9.17
Current task: _antigravity_ensure_acg_session
Blocked on: lib‑foundation v0.3.14 (5 fixes pending)

세 번째 계층은 memory-bank/activeContext.md가 이미 제공하는 내용입니다. 첫 번째와 두 번째 계층은 Cline이 자동으로 생성하고 유지 관리할 수 있는 부분입니다.

워크플로우

패턴:

1. Cline이 한 번 인덱싱 – 전체 코드베이스를 읽고 docs/index/structure.md와 docs/index/contracts.md를 생성한 뒤 커밋합니다.
2. Cline은 변경 시 업데이트 – 파일이 이동하거나 패턴이 바뀔 때 Cline이 인덱스를 업데이트합니다. 이것은 인간이 아니라 Cline의 반복적인 작업입니다.
3. 다른 에이전트는 인덱스로 시작 – Claude, Codex, Gemini는 인덱스를 컨텍스트 윈도우의 일부로 받아 탐색을 건너뛰고 바로 구현을 시작합니다.

Result: 에이전트가 방향성을 갖고 시작합니다. 이제 매 커밋마다 플러그인 패턴을 다시 발견하지 않아도 되며, 탐색 비용이 사라집니다.

이것이 바뀌는 점

• Token efficiency – 에이전트가 코드베이스를 다시 학습하는 데가 아니라 작업에 컨텍스트 창을 사용합니다. 200 k‑token 창에서는 이것이 상당합니다.
• Consistency – 모든 에이전트가 동일한 맵에서 시작합니다. Codex가 Claude가 모르는 명명 규칙을 만들지 않으며, 두 에이전트 모두 같은 계약을 읽습니다.
• Handoff clarity – 작업 중에 에이전트를 교체하면 새로운 에이전트가 이전 에이전트가 중단한 지점부터 이어받습니다. 인덱스는 결정된 내용을 알려주고, 메모리 뱅크는 진행 중인 내용을 알려줍니다. 재‑브리핑이 필요 없습니다.

더 깊은 패턴

멀티‑에이전트 워크플로는 공유 컨텍스트 문제를 겪습니다. 각 모델은 자체 컨텍스트 윈도우를 가지고, 각 세션은 새롭게 시작합니다. 코드베이스는 그들이 모두 공유하는 유일한 것이지만—컨텍스트로 구조화된 것이 아니라 단순히 코드일 뿐입니다.

인덱스가 다리 역할을 합니다. 인덱스는 저장소의 암묵적인 구조를 명시적으로 변환하여, 어떤 세션이든 어떤 에이전트든 탐색하고 활용할 수 있게 합니다.

에이전트가 더 똑똑해지는 것은 아니며, 단지 눈을 가리고 시작하지 않게 될 뿐입니다.

코드베이스가 공유 컨텍스트이며, 인덱스가 그 열쇠입니다.