agentdir: 원본은 그대로 두고 에이전트에게 작업하기 좋은 파일 구조를 따로 만들어주기

AI 에이전트를 사용할 때 자주 마주치는 문제가 있다. 파일은 많은데 정리가 되어 있지 않고, 폴더 구조는 사람이 과거에 일하던 방식 그대로 남아 있다. 그런데 우리는 그 상태 그대로 에이전트에게 "이 문서들 보고 정리해줘", "이 자료 기반으로 분석해줘", "관련 파일 찾아서 작업해줘"라고 요청한다.

Jeffrey Kim의 LinkedIn 글 표현처럼, 에이전트도 정리가 안 된 파일과 폴더를 보고 싶어하지 않는다. 정확히는, 그런 곳에서는 일을 잘하기 어렵다. 인간도 어지러운 바탕화면에서 원하는 파일을 찾는 데 시간을 쓰듯이, 에이전트도 지저분한 작업 공간에서는 탐색과 추론 비용을 낭비한다. 파일명이 제각각이고 비슷한 자료가 여러 위치에 흩어져 있으면, 에이전트는 컨텍스트를 잡기 전에 탐색에만 많은 토큰과 시간을 쓴다.

이때 사용할 수 있는 도구가 agentdir이다. Markr.AI 산하 오픈소스 조직 NomaDamas가 공개한 Rust 기반 프로젝트인데, NomaDamas는 RAG AutoML 프레임워크 AutoRAG를 만든 팀이기도 하다.

• GitHub: NomaDamas/agentdir
• 소개 글: Jeffrey Kim LinkedIn post
• 역할: 원본 폴더는 건드리지 않고 에이전트용 파일 구조를 따로 만드는 도구
• 핵심 상황: "사람에게 편한 폴더 구조"와 "에이전트가 일하기 좋은 폴더 구조"가 다를 때

agentdir는 원본 파일은 그대로 둔 채, 에이전트가 보기 좋은 별도의 파일 트리를 만들어주는 도구다. 사람이 쓰는 폴더 구조와 에이전트가 쓰는 폴더 구조를 분리하는 인프라라고 보면 된다.

agentdir가 하는 일

agentdir는 기존 파일을 실제로 옮기지 않고, 특정 작업에 맞는 가상의 폴더 구조를 만들어준다.

team-files/
  2023/
  2024/
  screenshots/
  회의록_최종진짜최종.md
  report_v2.pdf
  고객사자료/
  temp/

사람 입장에서는 익숙한 구조일 수 있다. 하지만 에이전트에게는 "무엇이 중요한 파일인지", "분석 대상은 어디인지", "보고서와 회의록은 어떻게 연결되는지"를 파악하기 어렵다.

agentdir를 쓰면 같은 파일들을 에이전트 작업 목적에 맞춰 이렇게 노출할 수 있다.

workspace/
  reports/
    q1-report.pdf
  meeting-notes/
    customer-meeting.md
  customer-materials/
    proposal.pdf
  references/
    screenshots/

중요한 점은 원본 파일은 움직이지 않는다는 것이다. 에이전트가 보는 구조만 새로 만들어진다. 단순 복사본을 만드는 방식도 아니기 때문에, 지원되는 파일시스템에서는 대용량 파일을 중복해서 들고 있을 필요가 없다. 내 바탕화면이나 공유 폴더는 그대로 복잡해도, 에이전트에게는 잘 정리된 작업 공간만 보여줄 수 있다.

아래 그림은 원본 폴더, 매핑, 읽기 전용 작업 뷰가 어떻게 분리되는지 요약한 것이다.

즉, agentdir는 다음과 같은 일을 한다.

• 원본 디렉토리를 가상 파일 트리에 매핑한다.
• 에이전트가 읽기 좋은 구조로 파일을 재배치한다.
• 원본 파일은 그대로 유지하고, 가상 뷰는 읽기 전용으로 만든다.
• 변경 사항을 감지해 작업 공간에 반영한다.
• macOS, Linux, Windows에서 동작한다.
• APFS, Btrfs, XFS 같은 CoW 지원 파일시스템에서는 대용량 파일도 중복 복사 비용 없이 다룰 수 있다.

왜 필요한가

에이전트를 쓸 때 많은 사람들이 모델 성능에만 집중한다. 하지만 실제 작업 품질은 모델만으로 결정되지 않는다.

에이전트가 어떤 파일을 보고, 어떤 순서로 탐색하고, 어떤 구조 안에서 판단하는지가 결과에 큰 영향을 준다. 에이전트를 실제 프로젝트나 데이터 폴더에 붙이면 처음 하는 일이 탐색이다. 깊은 트리를 ls로 훑고, 파일을 cat으로 열고, grep으로 검색한다. 잘 정리된 코드베이스라면 괜찮지만, 사람의 다운로드 폴더처럼 빌드 산출물, 대용량 데이터, 임시 파일이 뒤섞인 곳에서는 탐색만으로도 컨텍스트 예산이 줄줄 샌다. 정작 필요한 파일은 그 잡음 속 어딘가에 있다.

두 번째 문제는 덜 이야기되지만 더 위험하다. 에이전트가 탐색하는 그 폴더는 보통 에이전트가 수정도 할 수 있는 폴더다. 잘못된 write나 rm 한 번이 사용자의 원본을 건드린다. 사람이 쌓아온 디렉토리 구조나 파일을 에이전트가 마음대로 바꾸길 원하는 경우는 드물다. 파일명 변경, 폴더 이동, 삭제 같은 작업은 한 번 잘못되면 되돌리기 어렵고, 공유 드라이브나 고객사 자료라면 더더욱 조심해야 한다.

그렇다고 정리된 사본을 새로 복사하면, 멀티 GB짜리 PDF나 데이터셋이 레이아웃 수만큼 그대로 중복된다. 결국 "에이전트에게 깔끔하고 안전한 뷰를 주고 싶다"와 "원본을 옮기거나 복제하기는 싫다"가 충돌한다.

그래서 agentdir는 원본을 정리해주는 대신, 에이전트가 볼 수 있는 별도의 정리된 작업 공간을 만든다. 정리되지 않은 폴더를 그대로 에이전트에게 주면 다음 문제가 생긴다.

1. 탐색 비용이 커진다. 에이전트가 관련 파일을 찾기 위해 불필요한 디렉토리를 뒤진다.
2. 중요 파일을 놓치기 쉽다. 파일명이나 위치가 애매하면 에이전트가 핵심 자료를 발견하지 못할 수 있다.
3. 컨텍스트가 흐려진다. 작업과 무관한 파일까지 섞이면 에이전트가 목표를 잘못 이해할 수 있다.
4. 사람용 폴더 구조와 에이전트용 구조가 다르다. 사람은 날짜, 부서, 고객사 기준으로 정리하고 싶을 수 있지만 에이전트에게는 "분석 대상", "참고자료", "출력물", "검토 대상"처럼 작업 중심 구조가 더 유리하다.

agentdir의 핵심 가치는 여기에 있다.

원본 파일 구조는 유지하면서, 에이전트에게는 작업 목적에 맞는 깨끗한 파일 구조를 제공한다. 그리고 그 뷰를 통해서는 원본에 쓰지 못하게 막는다.

이 접근은 특히 문서, 리서치 자료, 고객사 파일, PDF, 이미지, 데이터셋처럼 코드가 아닌 파일을 다룰 때 유용하다.

기본 사용법

기본 사용 흐름은 간단하다. 먼저 CLI를 설치한다.

cargo install agentdir-cli

Python 패키지나 Node.js 패키지로도 사용할 수 있다.

pip install agentdir
npm install @nomadamas/agentdir

그다음 작업 공간을 만든다.

agentdir init ./workspace

원본 디렉토리를 가상 트리에 매핑한다.

agentdir -w ./workspace map ./team-files /files

이제 에이전트는 ./team-files 원본을 직접 뒤지는 대신, ./workspace 안의 정리된 구조를 기준으로 작업할 수 있다.

파일을 에이전트용 구조로 옮기고 싶다면 virtual namespace 안에서 이동하면 된다.

agentdir -w ./workspace mv /files/q1-report.pdf /reports/q1-report.pdf

여기서 중요한 점은 이 명령이 원본 파일을 실제로 옮기는 것이 아니라는 점이다. 에이전트가 보는 가상 구조만 바뀐다.

원본 파일 변경 사항을 반영하려면 refresh를 실행한다.

agentdir -w ./workspace refresh

계속 동기화하고 싶다면 watcher를 실행할 수 있다.

agentdir -w ./workspace watch --interval 60

이렇게 하면 원본 디렉토리의 변경 사항이 작업 공간에 반영된다.

에이전트 워크플로가 꼭 Rust나 CLI에서만 만들어지는 것은 아니다. 데이터 분석 스크립트는 Python에 있고, 자동화 도구는 Node.js에 있을 수 있다. 그래서 Python 바인딩에서는 같은 흐름을 이렇게 쓸 수 있다.

from agentdir import Workspace

ws = Workspace.init("./workspace")
ws.map("./team-files", "/files")
ws.mv("/files/q1-report.txt", "/reports/q1-report.txt")
ws.refresh()

여기서 핵심은 동작 방식이다. 이 흐름은 파일을 옮기는 것이 아니라 보여주는 경로를 바꾸는 식으로 동작한다.

실제 사용 예시는 조금 더 구체적으로 보면 이해가 쉽다.

고객사 자료를 에이전트 리뷰용 구조로 재배치하기

# 원본은 회사 공유 폴더 그대로 둔다
agentdir init ./agent-workspace
agentdir -w ./agent-workspace map ./customer-dropbox /raw

# 에이전트가 볼 구조를 작업 중심으로 만든다
agentdir -w ./agent-workspace mv /raw/회의록_최종진짜최종.md /inputs/meeting-notes/customer-kickoff.md
agentdir -w ./agent-workspace mv /raw/report_v2.pdf /inputs/reports/current-report.pdf
agentdir -w ./agent-workspace mv /raw/고객사자료/proposal.pdf /references/customer-proposal.pdf

# 이후 에이전트에게는 ./agent-workspace만 넘긴다

에이전트에게 전달하는 프롬프트도 훨씬 단순해진다.

./agent-workspace를 기준으로 고객사 제안서와 회의록을 검토해줘.
- /inputs: 분석 대상
- /references: 참고자료
- /outputs: 결과물을 저장할 위치

원본 폴더가 지저분하더라도 에이전트는 /inputs, /references, /outputs처럼 작업 의도가 드러나는 구조만 보면 된다. 이게 agentdir의 실용적인 포인트다.

사용하며 알게 된 점

도구가 실제로 약속을 지키는지 보려고, 어지러운 코퍼스를 하나 만들어 macOS(APFS)에서 측정했다. 300MB짜리 데이터 파일 하나와 다운로드 폴더처럼 흩어진 문서 여섯 개(PDF, 스크린샷, 계약서 초안, node_modules 잡파일 등)를 가상 트리에 매핑한 뒤, 같은 300MB 데이터셋을 다섯 개의 서로 다른 레이아웃에 동시에 노출했다.

측정 항목	결과
원본 전체를 가상 트리에 매핑	30ms (파일 7개 + 디렉토리 8개)
materialize 방식	reflinked 7 / copied 0 (전부 CoW 클론)
같은 300MB를 5개 레이아웃에 노출	du 논리 합계 1.5GB, 실제 추가 디스크 거의 0
대조: 같은 1.5GB를 일반 복사	0.23초 + 실제 디스크 1.5GB 사용
가상 뷰 파일 권한 (reflink 전략)	0o444, 그 경로로 쓰기 시도 차단됨. 원본은 쓰기 가능 유지
스냅샷 격리	스냅샷에 쓴 내용이 베이스 작업 공간으로 전파되지 않음
추적성	가상 경로 → 실제 원본 경로 역매핑 동작 확인 (export_mapping)

(단일 데모 기준이다. 절대 수치보다 동작의 성격에 주목해 달라. reflink 동작은 파일시스템에 의존하므로 APFS/Btrfs/XFS에서만 이렇게 나오고, ext4나 NTFS에서는 byte-copy로 폴백한다.)

이 데모가 확인한 건 측정 대상이 곧 도구의 약속이라는 점이다. "복사 없이 여러 레이아웃"은 reflinked 7/copied 0으로, "가상 뷰로는 원본에 못 쓴다"는 0o444 쓰기 차단으로, "스냅샷 쓰기가 베이스로 새지 않는다"는 스냅샷 격리로 확인된다. 반대로 이 데모가 측정하지 않은 것도 있다. 탐색 시 토큰/컨텍스트 절감, 실제 에이전트 루프에서의 동작, 동시 실행 충돌은 별도 검증이 필요한 영역이다. 참고로 위 표의 0o444 쓰기 차단은 reflink 전략에서 만든 가상 뷰에 한정된다.

규모를 키우면 차이가 더 분명하다. 50GB 코퍼스를 여덟 개 task-view에 노출하면 일반 복사로는 400GB가 들지만, reflink로는 추가 디스크가 거의 들지 않는다(이 50GB/400GB는 위 데모를 외삽한 추정치이며 직접 측정값은 아니다).

재현 메모: 측정은 agentdir 0.1.x의 Python 바인딩으로 짠 약 90줄 스크립트로, macOS(APFS)에서 돌렸다. 코퍼스는 300MB 더미 데이터 1개와 흩어진 문서 6개로 합성해 다섯 레이아웃에 노출했다. "추가 디스크 거의 0"은 du(논리 크기)가 아니라 reflinked=7/copied=0(CoW 블록 공유)과 동일 데이터를 일반 복사했을 때 1.5GB가 실제로 기록되는 대조로 확인한 값이며, df 단위의 정밀 측정은 아니다. 스냅샷·rglob 등 일부 기능은 현재 CLI가 아니라 바인딩에만 있어 측정도 바인딩으로 했다.

이 가상 뷰에는 원본으로 가는 쓰기 경로가 없다. 수정이 필요하면 에이전트가 아니라 신뢰된 오케스트레이터가 export_mapping으로 원본 실경로를 받아 거기서 고치는 식으로 역할을 분리한다.

동작 구조

레포 구조는 단순하다.

crates/
  agentdir/       Core Rust library
  agentdir-cli/   CLI
bindings/
  python/         PyO3 + maturin
  node/           NAPI-RS

코어는 Rust로 짜여 있고, 동일한 로직을 Rust 크레이트, Python(PyO3), Node(NAPI-RS) 세 채널로 배포한다. 핵심 컴포넌트는 Workspace, Catalog, Materializer, Reconciler로 나뉜다.

• 가상 네임스페이스 (Catalog): Catalog는 가상 경로와 실제 소스 경로의 매핑을 들고 있다. 내부적으로는 가상 경로 문자열을 키로 하는 해시맵 인덱스라 경로 조회가 평균 O(1)이고, 가상 경로는 OS와 무관하게 항상 /를 쓴다.
• CoW materialize (Materializer): Materializer는 그 매핑을 실제 디스크 위에 드러내는 역할을 한다. 기본 전략은 reflink다(APFS/Btrfs/XFS에서 블록 공유 클론, 그 외에는 byte-copy 폴백). 이 밖에 symlink, metadata만 두는 virtual 전략을 고를 수 있다.
• 읽기 전용 보장: reflink/byte-copy로 materialize된 파일은 0o444(Windows에서는 읽기 전용 속성)로 설정된다(symlink 전략은 이 보장에서 예외다). 쓰기는 원본 파일을 통해 이뤄져야 하고, 가상 트리는 탐색과 소비를 위한 뷰로 남는다.
• 변경 추적 (Reconciler): 기본은 mtime + 파일 크기 비교(빠름)이고, 옵션으로 SHA-256 검증을 켜면 mtime/size가 그대로인 조용한 수정까지 잡는다. 동기화는 on-demand refresh 또는 장기 실행 watch(파일 이벤트 약 500ms 디바운스 + 기본 60초 주기 전체 재스캔)로 한다.
• 원자적 manifest: 상태는 .agentdir/manifest.json에 저장되는데, 임시 파일에 쓰고 fsync 후 rename하는 방식을 쓴다. 중간에 프로세스가 죽어도 반쯤 쓰인 JSON이 남지 않게 하려는 선택이다.

동기화는 자동 마법이 아니라 명시적(refresh / watch)이고, 원본 → 가상 한 방향이다. 무엇을 어떤 구조로 보여줄지는 여전히 사람이나 상위 오케스트레이터가 결정한다. 화려하진 않지만 이런 구현이 파일 시스템 도구에서는 꽤 중요하다. 에이전트가 읽는 작업 트리가 깨지면 다음 단계의 추론도 같이 흔들리기 때문이다.

한계와 주의점

사용하며 마주친 한계들이다.

• read-only 보장은 가상 뷰에 한정된다. 0o444는 뷰 경로에 대한 것이고, 에이전트 런타임이 원본 경로에 접근 가능하면 별도 sandbox/접근 스코핑이 필요하다.
• 비CoW 파일시스템에서는 디스크가 중복된다. reflink가 안 되는 ext4/NTFS/exFAT에서는 byte-copy로 폴백하므로, "복사 없이"의 이점은 APFS/Btrfs/XFS에 한정된다. Linux의 FUSE, Windows의 ProjFS 같은 대안은 가능하지만 장기 실행 프로세스나 OS 기능 의존성이 커져 현재 범위 밖에 둔다.
• 스냅샷은 reflink가 아니라 symlink로 구현돼 있다. README는 스냅샷을 "CoW fork"로 소개하지만, 실제 구현은 베이스 작업 공간의 파일을 심볼릭 링크로 가리키다가 쓰기 시점에 실제 파일로 분리하는 방식이다. 쓰기가 베이스로 전파되지 않는 것은 확인했지만, 동시 실행 충돌 같은 더 넓은 격리는 별도 검증이 필요하다.
• 변경 감지가 모든 수정을 잡지는 않는다. 기본 mtime/size 비교는 mtime/size가 보존되는 복사나 동기화 환경의 조용한 수정을 놓칠 수 있어, 그럴 땐 SHA-256 검증을 켜야 한다(전체 재해시 비용이 든다).
• 일부 기능은 바인딩 전용이다. 스냅샷(snapshot), rglob, exists 등은 현재 Python/Node 바인딩에는 있지만 CLI에는 없다.
• 이 도구는 두뇌가 아니다. 무엇을 어떤 구조로 재배치할지 결정하는 오케스트레이터, 파일 파싱, 인덱싱, 검색은 모두 명시적 비범위다.

기존 방식과 비교

에이전트에게 파일을 주는 방법은 이미 여럿 있다. agentdir의 자리는 그 사이의 빈칸을 보면 드러난다.

접근	해결하는 것	데몬/root/마운트	한계
MCP 파일시스템 서버	접근 폴더 스코핑	프로세스	원본 트리 그대로 노출(정리 안 됨), read-only는 서버 정책
OverlayFS	쓰기 격리(리눅스 CoW)	root + 마운트	리눅스 전용, 구조 재배치 아님
git worktree	코딩 에이전트 격리	없음(git 필요)	git 저장소 전용, 여전히 수정 가능한 전체 트리
FUSE 기반 AgentFS류	에이전트 전체 상태/메모리 substrate	데몬 + DB + 마운트	무거운 스택
reflink/cp --reflink	대용량 파일 무복제 클론	없음	복사 프리미티브일 뿐, 레이아웃·안전 경계 아님
agentdir	정돈된 읽기 전용 뷰 + 무복제	없음	어린 프로젝트, 일부 기능 바인딩 전용

agentdir가 메우는 칸은 "정돈된 읽기 전용 뷰 + 무복제"다. 마운트도, root도, 상시 데몬도 없는 유저스페이스 도구이고, reflink/byte-copy 전략에서는 가상 트리가 실제 일반 파일이라 심볼릭 링크를 무시하는 도구도 내용을 본다. 그리고 가상 뷰의 read-only가 서버 정책이 아니라 파일 권한이라는 점이 MCP 서버의 ro 플래그와 갈라지는 지점이다.

활용 예시

agentdir는 다음과 같은 상황에서 특히 유용하다.

1. 에이전트에게 문서 묶음을 넘겨야 할 때

회의록, PDF, 발표자료, 스프레드시트, 이미지가 한 폴더에 섞여 있다면 에이전트가 보기 좋은 구조로 재배치할 수 있다.

/inputs
/references
/reports
/customer-materials
/outputs

이런 식으로 정리하면 에이전트가 작업 목적을 훨씬 빨리 이해한다.

2. 공유 문서 더미를 복사 없이 재배치할 때

회사 공유 드라이브, 고객사 자료, 기존 프로젝트 폴더는 임의로 구조를 바꾸기 어렵다. 하지만 에이전트 작업을 위해서는 구조를 바꾸고 싶다. agentdir는 이 둘을 분리한다.

• 사람과 조직은 기존 폴더 구조를 계속 사용한다.
• 에이전트는 별도의 정리된 작업 공간을 사용한다.

멀티 GB 코퍼스도 CoW 파일시스템 기준으로는 복사 없이 목적별 레이아웃으로 보여줄 수 있다.

3. 여러 에이전트에게 서로 다른 관점을 제공하고 싶을 때

같은 파일 묶음이라도 에이전트 역할에 따라 필요한 구조가 다를 수 있다. 예를 들어 하나의 고객사 자료 폴더를 두고, 분석 에이전트와 문서 작성 에이전트에게 서로 다른 뷰를 줄 수 있다.

analysis-workspace/
  inputs/
  data/
  evidence/
  outputs/

writing-workspace/
  source-materials/
  outline/
  drafts/
  references/

이렇게 나누면 분석 에이전트는 근거 수집에 집중하고, 작성 에이전트는 초안 작성 흐름에 집중한다. 원본 파일을 복사해서 여기저기 흩뿌리는 대신, 에이전트별 작업 공간만 다르게 구성하는 방식이다.

4. 세션·실험마다 격리가 필요할 때

스냅샷으로 트라이얼마다 격리된 작업 뷰를 만들 수 있다. CoW 파일시스템에서는 이 비용도 작게 가져갈 수 있다. 다만 현재 스냅샷은 바인딩 전용이고 symlink 기반임에 유의한다.

이럴 때는 권하지 않는다

• 주력 환경이 ext4나 NTFS면 reflink가 byte-copy로 폴백하므로 무복제 이점이 사라진다. 대용량 코퍼스를 여러 레이아웃에 노출하려는 목적이라면 다른 선택지를 본다.
• 에이전트가 원본 경로에 직접 접근할 수 있는 구성이면 0o444만으로는 부족하다. 이 경우 가상 뷰 권한보다 샌드박스나 접근 스코핑이 먼저다.
• 대상이 이미 잘 정리된 코드베이스면 git worktree로 충분하다.

agentdir가 하지 않는 것

agentdir는 파일을 "이해"하거나 "자동 분류"하는 AI 도구는 아니다. README에서도 명확히 밝히듯이, 이 도구의 목표는 다음이 아니다.

• LLM 통합
• 의미 기반 파일 분류
• 전문 검색
• 파일 포맷 변환
• 문서 내용 파싱
• 에이전트가 어떤 구조로 정리해야 하는지 판단하는 일

즉, agentdir는 지능형 분류기가 아니라 에이전트가 쓰기 좋은 파일 레이아웃을 만들기 위한 파일 시스템 인프라다. 검색 엔진도 아니고, 임베딩 인덱스도 아니고, LLM 통합 레이어도 아니다. 그 선 덕분에 오히려 역할이 명확해진다. 에이전트나 사람이 "어떤 구조가 좋은지" 결정하고, agentdir는 그 구조를 안전하게 materialize한다.

RAG·AutoRAG 관점에서 (Braincrew의 해석)

RAG/에이전트 파이프라인 관점에서 agentdir는 인제스트 직전의 코퍼스 뷰 레이어로 읽힌다. 파싱·인덱싱 전에 에이전트에게 정돈된 코퍼스를 보여주고, 평가 트라이얼마다 격리 스냅샷으로 재현 가능한 환경을 구성하는 식이다. 또 가상 경로 기준으로 인덱싱한 청크를 export_mapping으로 실제 원본 파일까지 되돌리면 인용 출처 추적에도 쓸 수 있을 것으로 보인다. AutoRAG가 코퍼스에 맞는 최적 RAG 구성을 오프라인에서 찾는 도구라면, 그 입력이 되는 코퍼스를 정리해 보여주는 인프라가 agentdir라는 분업으로 이해할 수 있다.

다만 agentdir 저장소는 RAG도 AutoRAG도 전혀 언급하지 않는다. README는 "AI 에이전트, 스크립트, 사람"을 위한 범용 가상 파일트리로 소개하고, AI/LLM 통합과 검색·인덱싱을 명시적 비범위로 둔다. 위 RAG 연결은 같은 팀이 만든 도구라는 사실과 각 도구의 설계 의도에 근거한 Braincrew의 해석이지, 도구가 주장하는 통합이 아니다.

정리

agentdir는 기존 파일을 건드리지 않으면서 에이전트에게 더 좋은 작업 공간을 제공한다. 정리되지 않은 폴더를 그대로 에이전트에게 던지는 대신, 목적에 맞는 가상 폴더 구조를 만들어주고, 그 뷰를 통해서는 원본에 쓰지 못하게 막는다.

직접 돌려본 결과로 남은 건 두 가지다. CoW 파일시스템(APFS/Btrfs/XFS)에서는 같은 데이터셋을 여러 레이아웃에 노출해도 reflink 덕분에 추가 디스크가 거의 들지 않았고, reflink 전략으로 만든 가상 뷰 파일은 0o444로 잠겨 그 경로로는 원본을 건드릴 수 없었다. agentdir는 에이전트에게 정돈된 읽기 전용 뷰를 무복제로 제공하는 파일 시스템 인프라다.

References

• agentdir (NomaDamas/agentdir) - 에이전트용 읽기 전용 가상 파일트리
• Jeffrey Kim LinkedIn 소개 글 - 에이전트는 정리 안 된 파일을 보고 싶어하지 않는다
• AutoRAG (Marker-Inc-Korea/AutoRAG) - RAG AutoML 프레임워크
• About reflinks - CoW reflink 클론 동작 설명
• Linux Kernel: Overlay Filesystem - read-only lower + writable upper CoW
• Model Context Protocol: Filesystem server - 에이전트 파일 접근의 사실상 표준
• Anthropic: Code execution with MCP - 에이전트에게 파일시스템으로 점진적 컨텍스트를 주는 패턴