지난주에 저는 우리가 아직 만나보지 못한 코로나바이러스에 대한 백신을 설계한 AI에 관한 글을 읽었습니다 (ScienceDaily). 케임브리지에서 첫 번째 임상 시험을 진행했고, 39명의 지원자가 항원을 투여받았습니다.
알고리즘이 바이러스의 전체 유전자군을 분석하고, 아직 동물 사이에서 순환하며 인간에게 전염되기를 기다리고 있는 변종들에 대한 방어책을 설계했다는 사실이 믿기지 않습니다. 그런데 제가 문서 목록에서 최신 브리핑을 가져오라고 요청하면, 제 에이전트는 거의 2분 동안 제 볼트에서 잘못된 파일을 열어보다가 3개월 전 브리핑을 보여주기도 합니다.
케임브리지가 맞춤 훈련된 AI를 사용한다는 건 알지만, 제가 말씀드리고 싶은 것은 AI가 할 수 있는 일과 설정이 AI가 할 수 있게 해주는 일 사이의 격차가 여러분의 워크플로우와 생산성을 결정한다는 점입니다.
저는 최근까지 의도적으로 스캐폴딩을 구축한 적이 없었습니다. 에이전트 주변에 우연히, 폴더 하나씩 쌓여가면서, 에이전트는 제가 스스로 만든 엉망진창 속에서 길을 잃기 시작했습니다.
그래서 하루를 시간을 내서 모든 실패의 시간을 측정했고, 패턴이 드러났습니다. 이번 호에서는 세상이 천재라고 부르는 AI 에이전트가 왜 쉬운 작업에서 계속 넘어지는지, 그리고 그 문제를 해결해 에이전트를 다시 내 편으로 만드는 방법을 알려드립니다.
이 글에서 다루는 내용:
- 폴더 구조가 에이전트의 발목을 잡는 이유는 제 생각 방식대로 정리되어 있지, 에이전트가 탐색하는 방식대로 정리되어 있지 않기 때문입니다.
- 모든 주요 폴더의 루트에 있는 하나의 인덱스 파일이 느린 검색을 30초 만에 끝내는 읽기로 바꿔줍니다.
- 에이전트 주변의 보이지 않는 스캐폴딩이 에이전트 자체의 능력보다 더 중요하며, 이를 구축하는 방법을 소개합니다.
- 5분이면 실행할 수 있는 진단 테스트로 폴더 구조가 실제 문제인지 확인하는 방법.
에이전트가 볼 수 없는 구조
저는 대부분의 사람들처럼 볼트를 정리했습니다. 기사, 연구 자료, 에셋, 전략 문서 등 각각의 폴더를 따로 만들었죠. 이 구조는 콘텐츠 유형별로 생각하는 제게는 깔끔하게 느껴졌습니다. 폴더는 제 카테고리에 맞춰져 있어서 어디를 봐야 할지 고민할 필요가 없습니다. 초안은 기사 폴더에, 노트는 연구 폴더에, 파일 시스템은 자동으로 돌아갑니다.
하지만 에이전트는 카테고리로 생각하지 않습니다. Hermes 에게 제품 출시 계획을 요청하면, 해당 작업은 여러 폴더에 흩어져 있는 전략 노트, 브랜드 가이드라인, 이전 출시 자료들을 가져와야 합니다.
이러한 맥락 조각들은 제 콘텐츠 유형 구조 내에서 서로 다른 곳에 위치합니다. 제 에이전트는 매번 모든 곳을 검색해야 하며, 어떤 초안이 현재 작업 중인 것인지, 어떤 것이 보관된 것인지, 또는 어떤 연구 노트가 이번 달 것인지 6개월 전 것인지 알지 못합니다.
콘텐츠 유형별 조직은 인간에게 완벽하게 작동합니다. 여러분은 평생을 카테고리 아래에 파일을 정리해 왔고, 여러분의 두뇌는 자동으로 상호 참조를 수행합니다. AI도 같은 방식으로 작동할 거라고 기대하는 것은 자연스러운 일이지만, 실제로 에이전트는 그 상호 참조를 수동으로 수행해야 하며, 바로 여기서 구조가 무너집니다.
에이전트 주변의 구조가 에이전트 자체의 능력보다 더 많은 일을 합니다.
패턴을 발견하고 나니 원인은 명확했습니다. 저는 파일이 어디에 있는지 기억하는 인간의 두뇌를 위해 볼트를 구축해 놓고, 매번 처음부터 검색해야 하는 에이전트에게 넘겨준 셈이었고, 이것이 폴더 혼란 아래 숨겨진 진짜 문제를 드러냈습니다.
검색자에게는 지도가 필요합니다. 지도가 없으면 에이전트는 어둠 속을 걸으며 모든 파일이 정답일 수도 있다고 생각하기 때문입니다.
능력이 낭비되는 곳
Hermes 는 올바른 파일을 찾기 전에 여러 파일을 열어보거나, 현재 파일이 다른 곳에 있는데도 보관된 버전을 가져오곤 했습니다. 더 나쁜 것은, 상황상 답이 명백해야 함에도 어떤 파일을 사용할지 질문을 하기도 했습니다. 이 문제는 제가 사용한 모든 모델(Opus, GPT 5.5, Qwen, GLM 포함)에서 발생했습니다.
패턴은 계속 반복되었고, 저는 같은 느린 검색이 작업마다 반복되는 모습을 지켜볼 수밖에 없었습니다.
에이전트가 무언가를 찾을 수 있는 충분한 능력을 갖추고 있었음에도, 폴더 구조가 실제 작업에 도달하기도 전에 주요 병목 현상이 되어 버렸습니다.
제가 한계점에 도달한 것은 실패 시간을 측정하던 날이었습니다. Hermes 가 올바른 파일에 도달할 때까지 얼마나 많은 파일을 열었는지, 그리고 그 시간이 얼마나 걸렸는지 추적했습니다. 다섯 가지 일반적인 작업은 변경 전에 다음과 같았습니다.
변경 전:
- 현재 기사 브리핑 찾기: 7개 파일 열림, 올바른 파일까지 2:00;
- 브랜드 색상 정의 찾기: 5개 파일 열림, 1:12;
- 계획을 위한 기사 큐 확인: 4개 파일 열림, 0:48;
- 동일 주제의 이전 기사 찾기: 6개 파일 열림, 1:36;
- 출시를 위한 프로모션 전략 가져오기: 3개 파일 열림, 0:34.
대략적인 실험이므로 정확한 수치는 방향성으로만 참고해 주세요.
모든 작업이 여러 폴더를 거쳤습니다. 대부분의 작업은 활성 버전을 찾기 전에 보관된 버전을 열었습니다. 제 에이전트는 제 역할을 수행하는 대신 탐색에 능력을 소모하고 있었습니다. 한 번의 출시 계획에는 세 개의 다른 폴더에 있는 세 개의 파일이 필요했는데, 에이전트가 올바른 파일을 찾기 전에 세 번의 잘못된 시도를 하는 모습을 지켜봐야 했습니다.
글을 쓰고, 코딩하고, 계획을 세우는 에이전트가 대부분의 시간을 무언가를 찾는 데 사용해서는 안 됩니다.
작동하는 가장 작은 우리
한 가지 관심사당 하나의 폴더, 순서를 위한 번호 매기기, 그리고 모든 것을 매핑하는 INDEX.md 가 루트에 위치합니다. 이것이 전체 해결책이며, 세부 사항은 함께 작동하는 세 가지 규칙에 담겨 있습니다.
각 주요 폴더의 루트에 있는 INDEX.md 는 지도입니다. 모든 하위 폴더와 표준 파일, 그리고 에이전트가 시작해야 할 위치를 나열합니다. 제 에이전트는 이 파일을 먼저 읽고 다른 어떤 것도 건드리기 전에 내부에 무엇이 있는지 알게 됩니다. 에이전트가 작업 중인 내용을 알기 전에는 작업을 시작할 수 없는 소프트 승인 게이트와 같다고 생각하시면 됩니다.
재구성 후 제 브랜드 폴더 구조는 다음과 같습니다.
105.Brand/2├── INDEX.md3├── 01.Brand System/4├── 02.Editorial Strategy/5├── 03.Promotion/6├── 04.Public Deliverables/7├── 05.Operating Plan/8└── 06.Archived/
이 구조는 콘텐츠 유형 대신 관심사별로 구성됩니다. 각 관심사는 고유한 폴더를 가지므로 브랜드 작업은 브랜드 작업과 함께, 전략은 전략과 함께 유지됩니다. 제 에이전트는 거기에 속하지 않는 무언가를 찾기 위해 경계를 넘지 않습니다.
폴더 번호는 알파벳 순서 정렬에 의존하는 대신 읽기 순서를 명시적으로 만듭니다. 01. Brand System 은 02. Editorial Strategy 보다 먼저 읽힙니다. 제 에이전트는 추측하지 않습니다. 폴더 내부의 번호는 파일에 대해서도 동일한 역할을 하므로, 에이전트는 02. Previous Articles 보다 01. Articles 가 시작점이라는 것을 알게 됩니다.
저도 기억하기 쉽도록 폴더 이름 앞에 번호를 붙입니다.
이렇게 하면 제 $30 Hermes 스택이 수십 개의 폴더를 쉽게 이동할 수 있으며 에이전트가 길을 잃지 않습니다.
보관된 자료는 06.Archived 에 있으며, 오래된 브리핑과 폐기된 계획은 그곳에서 대기합니다. 제 에이전트는 제가 특별히 과거 컨텍스트를 요청하지 않는 한 그곳을 찾지 않는다는 것을 알고 있습니다. 이러한 분리가 활성 폴더를 깨끗하게 유지하고 검색 속도를 빠르게 유지하는 비결입니다.
에이전트가 기본적으로 해당 경계를 넘지 않도록 지시받은 후, 활성 폴더 내의 모든 작업이 더 빨라졌습니다.
제 INDEX.md 는 다음과 같습니다.
1# Brand Index23이 폴더는 현재 브랜드 시스템을 보관합니다.45## 폴더 맵67| 폴더 | 목적 | 업데이트 |8|---|---|---:|9| `01.Brand System/` | 시각적 아이덴티티, 주제 범위, 어조 | 2026-06-11 |10| `02.Editorial Strategy/` | 기사 방향, 제목 규칙, 큐 | 2026-06-11 |11| `03.Promotion/` | 출시, 배포, 도구 전략 | 2026-06-11 |1213## 표준 파일1415| 파일 | 목적 |16|---|---|17| `01.Brand System/01. Brand System.md` | 시각적 아이덴티티, 색상, 타이포그래피 |18| `02.Editorial Strategy/01. Articles.md` | 기사 큐, 제목 규칙 |1920## 시작 위치2122- 미션을 확인하려면 `01.Brand System/04. Direction.md` 부터 시작23- 기사 선택에는 `02.Editorial Strategy/01. Articles.md` 사용
INDEX.md 는 세 가지 버전을 거쳤습니다. 첫 번째 버전은 브랜드 폴더 내의 모든 파일을 나열하여 40줄에 달했습니다. 기술적으로는 완벽했지만 에이전트가 매번 이를 파싱해야 했고 길이가 자체적인 오버헤드가 되었습니다. 두 번째 버전은 너무 짧아 15줄 정도였고, 에이전트는 여전히 제가 답하지 않은 질문을 했습니다. 이 세 번째 버전은 하위 폴더와 표준 파일만 나열하고, 에이전트에게 시작점을 알려주는 짧은 "시작 위치" 섹션을 포함합니다.
제가 에이전트에게 출시를 위한 프로모션 전략을 가져오라고 요청하면, 에이전트는 05.Brand/INDEX.md 를 읽고, 03.Promotion/01. Promotion Strategy.md 를 열어 작업을 시작합니다. 재구성 후의 시간은 다음과 같습니다.
재구성 후:
- 현재 기사 브리핑 찾기: 1개 파일 열림, 0:10
- 브랜드 색상 정의 찾기: 3개 파일 열림, 0:22
- 계획을 위한 기사 큐 확인: 1개 파일 열림, 0:10
- 동일 주제의 이전 기사 찾기: 2개 파일 열림, 0:18
- 출시를 위한 프로모션 전략 가져오기: 1개 파일 열림, 0:12
가장 느렸던 작업이 2분에서 26초로 줄었고, 가장 빠른 작업은 약 10초 만에 실행되었습니다. 제 에이전트는 INDEX.md 를 열고, 필요한 시작점을 따라가며, 헤매지 않고 작업을 시작합니다. 에이전트 측에서는 어떤 능력도 변경되지 않았습니다. 폴더 구조가 작업이 시작되기도 전에 능력의 대부분을 낭비하는 것을 막았습니다.
폴더 구조는 제가 만든 우리로, 에이전트가 할 수 있는 일을 제한하지 않으면서 에이전트가 움직이는 방식을 제한합니다. 우리 안에서 에이전트는 자유롭게 움직입니다. 우리가 없으면 Hermes 는 방황하는 경향이 있고, 저는 시간을 낭비하며 에이전트를 올바른 파일로 안내해야 합니다.
Hermes 로 전환하면서 파일, 제공자, 메모리 전반에 걸쳐 이러한 종류의 시스템을 한 번에 구축할 수 있었고, INDEX.md 패턴은 일상적으로 가장 큰 차이를 만든 가장 작은 요소였습니다.
모든 우리에는 자물쇠가 있다
제 첫 번째 실수는 모든 하위 폴더에 INDEX.md 를 추가한 것이었습니다. 지도가 너무 많으면 에이전트는 작업을 수행하는 대신 인덱스를 읽는 데 시간을 소비합니다. 저는 Brand 나 Editorial Strategy 와 같이 지도가 필요한 충분한 하위 폴더가 있는 주요 폴더의 루트에만 INDEX.md 를 유지합니다. 파일이 4~5개뿐인 작은 하위 폴더 내에서는 Hermes 가 지도 없이 직접 탐색합니다.
번호 매기기는 새 폴더를 추가할 때 번거로울 수 있다는 점을 명심하세요. 새 폴더가 시퀀스에서 어디에 맞을지 결정해야 하며, 때로는 모든 것을 다시 번호 매기기보다는 끝에 추가하기도 합니다. 괜찮습니다. 번호가 방향성만 제공한다면 완벽할 필요는 없습니다. 완벽하게 정렬된 폴더가 목표는 아니며, 그렇게 생각하면 실용적인 해결책이 미용 프로젝트로 변질됩니다.
더 큰 실수는 에이전트가 혼란을 보이기 전에 구조를 구축하는 것입니다. 대부분의 사람들은 에이전트 설정을 과도하게 엔지니어링하는데, 이는 적절한 인프라가 필요하다고 생각하기 때문입니다.
제 현재 규칙은 MCP, CLI, 또는 자체 도구를 선택하는 것과 동일한 원칙을 따릅니다. 작업을 완료하는 가장 작은 인터페이스를 사용하는 것입니다. 에이전트가 길을 잃을 때만 구조를 추가하고, 특정 문제를 해결하는 데 충분한 구조만 추가하세요.
제가 겪은 또 다른 실패는 구조 안에 구조를 중첩시킨 것이었습니다. 모든 것을 완벽하게 분류하기 위해 하위 폴더 안에 하위 폴더를 추가했고, 2단계 계층 구조가 5단계로 변했습니다. 그러면 에이전트는 단일 파일에 도달하기 위해 여러 개의 INDEX 파일을 읽고 여러 번호 시퀀스를 파싱해야 했습니다. 이러한 추가 레벨을 다시 평평한 하위 폴더로 축소하자 탐색 속도가 다시 빨라졌습니다.
깊이는 빠른 파일 조회의 적이며, 대부분의 재구성은 정밀하다고 생각하며 깊이를 추가합니다.
재구성하기 전에 측정하세요
폴더 하나를 건드리기 전에, 에이전트가 가장 자주 처리하는 세 가지 실제 작업에 대해 이 테스트를 실행하세요. 각각의 시간을 측정하고, 올바른 파일을 찾을 때까지 몇 개의 파일을 여는지 기록하세요. 잘못된 파일을 선택하거나 어떤 파일을 사용할지 묻기 위해 멈추는 횟수를 추적하세요.
에이전트가 30초 이상 걸리거나 3개 이상의 잘못된 파일을 여는 작업이 있다면, 그 작업 뒤에 있는 폴더가 깨져 있다는 신호입니다.
가장 자주 발생하는 실패 하나를 선택하세요. 해당 폴더를 열고 모든 하위 폴더와 중요한 파일, 그리고 에이전트가 시작해야 할 위치를 나열하는 INDEX.md 를 작성하세요. 저장하세요. 동일한 작업을 다시 실행하세요.
에이전트가 30초 이내에 올바른 파일을 찾으면 수정이 효과가 있었던 것이며, 이제 패턴을 알게 된 것입니다. 다음으로 깨진 폴더에 동일한 패턴을 적용하세요. 여전히 실패한다면 문제는 번호 매기기 또는 폴더당 하나의 관심사 원칙일 가능성이 높으며, 이 두 가지가 다음으로 수정해야 할 사항입니다.
가장 많은 시간을 낭비하는 하나의 폴더부터 시작하여 수정하고, 준비가 되었을 때만 다음 폴더로 넘어가세요.
여전히 휘어지는 막대
보관된 콘텐츠는 때때로 컨텍스트를 위해 오래된 브리핑이 필요할 때 참조됩니다. 제 에이전트는 활성 폴더 대신 06.Archived 를 봐야 한다는 것을 알아야 하며, INDEX.md 에서 이 내용을 언급하여 과거 자료가 어디에 있는지 알 수 있도록 합니다. 이 노트가 없으면 에이전트는 보관된 콘텐츠가 존재하지 않는다고 가정합니다.
또한, Obsidian Sync 는 기기 간에 깔끔하게 동기화되지 않을 때 가끔 문제를 일으킵니다. 노트북에서 파일을 업데이트했지만 VPS 에 여전히 이전 버전이 남아 있으면, Hermes 는 VPS 복사본을 로드하여 현재 진실의 원천으로 취급합니다. 이는 폴더 구조 문제라기보다는 동기화 문제에 가깝지만, 에이전트가 앞에 있는 파일만 보기 때문에 폴더 시스템 내에서 문제로 나타납니다.
번호 매기기는 폴더가 너무 많아져 시퀀스가 의미 없어질 때 깨집니다. 한 레벨에 10~12개 이상의 번호가 매겨진 항목이 있으면 번호가 임의적이 되기 시작합니다.
저는 주요 카테고리를 그 임계값 아래로 유지하고, 최상위 레벨을 확장하는 대신 내부에 더 깊은 구조를 중첩시키려고 노력합니다.
이름 변경은 또 다른 마찰 요인입니다. 재구성할 때 때로는 폴더의 목적에 더 잘 맞도록 이름을 변경하는데, 업데이트하기 전까지는 이전 이름을 참조하는 모든 INDEX.md 가 깨집니다. 이제는 폴더 이름을 한 번 설정하고 그대로 두려고 노력합니다. 약간 어색한 이름이 깨진 참조보다 비용이 덜 들기 때문입니다.
이 구조는 콘텐츠 중심 워크플로우와 계획 중심 워크플로우에 가장 잘 작동합니다. 순수 코드나 데이터 중심 설정은 완전히 다른 구성 원칙이 필요할 수 있으며, INDEX.md 패턴이 모든 탐색 문제를 해결하는 것은 아닙니다.
이 글에서 제가 쓴 모든 내용은 하나의 본능으로 거슬러 올라갑니다. 중요한 레이어를 소유하라는 것입니다. 저는 어떤 회사도 제 도구를 통제할 수 없도록 스택을 구축했습니다. 어떤 혼란도 제 에이전트를 통제할 수 없도록 볼트를 구축했습니다. 제공자에서 폴더, 그리고 앞으로 올 모든 것에 이르기까지 동일한 원칙입니다.
주변의 스캐폴딩이 망가져 있으면 능력은 값싸게 느껴집니다. 스캐폴딩을 구축하면 능력은 저절로 따라옵니다. 하나의 인덱스 파일과 폴더 이름 앞의 몇 개의 숫자가 방황하는 에이전트와 제대로 작동하는 에이전트의 차이를 만듭니다.
도움이 되셨다면 @wandermist 를 팔로우하여 더 많은 콘텐츠를 확인하세요!
