AI 도구가 코드베이스를 진정으로 확장하기 위해 파일 시스템 에이전트가 필수적인 이유

샌드박스(Sandboxed) 처리된 AI 에이전트는 더 안전하지만, 여러분의 코드베이스에 대해서는 눈이 멀어 있습니다. 파일 시스템 에이전트(File-system agents)는 위험할 수 있지만, AI 코딩 도구가 여러분과 함께 마지막 단계(last mile)를 완수할 수 있는 유일한 방법입니다. 즉, 빈 무대 위에서 환각(hallucination)을 일으키는 대신, 실제로 코드를 확장하고 연결(wiring)하는 것입니다. 이러한 차이는 학술적인 논쟁이 아닙니다. 여러분의 코딩 에이전트가 기능을 출시할 수 있는 부조종사(co-pilot)가 될 것인지, 아니면 단순히 코드 구문만 아는 채팅창이 될 것인지를 결정합니다.

AI 네이티브 템플릿은 에이전트가 실제 파일을 보고 형성할 수 있을 때만 작동합니다. 모든 OTF 키트는 기본적으로 코드베이스 형태로 제공됩니다. 여기에 CLAUDE.md, .cursorrules, 그리고 트리 내에 직접 작성된 AI 설정 파일이 포함됩니다. 그 이유는 계약의 목적이 PDF나 일회용 블랙박스를 전달하는 것이 아니라, 작동 가능한 시작점을 제공하는 것이기 때문입니다.

핵심적인 차이: 샌드박스 에이전트 vs 파일 액세스

코드 AI 에이전트에는 두 가지 종류가 있습니다. 안전하고 제한된 샌드박스 내부에서 실행되는 에이전트(실제 파일 I/O 없음, 읽기 전용 AST, 때로는 스니펫이나 project.json에 대한 액세스만 허용)와, 여러분의 실제 파일 트리(file tree)를 조사하고 재작성할 수 있는 에이전트입니다.

샌드박스 에이전트 (Sandboxed agent):

컨텍스트(context)로 전송된 내용(하나의 .py 파일, 프롬프트, 단일 붙여넣기, 또는 합성된 트리 등)만 볼 수 있습니다.
모든 쓰기 작업은 시뮬레이션되거나, 패치(patch) 형태로 스테이징되거나, 마크다운(markdown)으로 렌더링됩니다. 디스크에 직접적인 변경 사항이 적용되지 않습니다.

파일 시스템 에이전트 (File-system agent):

여러분의 레포지토리(repo) 경로를 부여받습니다.
여러분의 체크아웃(checkout) 상태에 있는 실제 파일을 읽고, 재작성하고, 생성하고, 삭제합니다.

이 차이는 다음 세 가지 작업에서 결정적입니다:

수십 개의 파일에 걸친 코드 조사 — 파일 에이전트만이 대규모로 목록을 나열(list), 검색(grep) 또는 리팩터링(refactor)할 수 있습니다.
스키마 인지 변경 (Schema-aware changes) — 데이터베이스, 라우팅(routing) 또는 빌드(build) 수정은 종종 여러 파일을 동기화해야 합니다.
실제 앱에 새로운 기능 연결 (Wiring new features into the real app) — 파일 에이전트만이 새로운 컴포넌트를 생성한 후 임포트(import), 테스트, 빌드 설정 및 라우트를 업데이트할 수 있습니다.

여러분의 코딩 부조종사가 단순한 장난 수준의 변경을 넘어설 수 있기를 원한다면, 실제 트리에 접근할 수 있어야 합니다. 왜 이 경계선이 자주 그어지는지, 그리고 왜 OTF가 이 경계를 넘어서는 데 베팅하는지 알아보겠습니다.

왜 그렇게 많은 도구가 기본적으로 샌드박스 에이전트를 사용하는가

너무 많은 AI 개발 도구들이 샌드박스 (sandbox) 경계에서 멈춰버립니다. 이들은 고립된 코드 스니펫 (snippets)이나 파일 단위로 작동하거나, 기껏해야 인덱서 (indexers)와 부분적인 AST (Abstract Syntax Tree) 스냅샷으로 구축된 코드베이스의 합성된 "뷰 (views)" 위에서 작동합니다.

이유는 무엇일까요? 현실적인 이유는 다음과 같습니다:

안전성 (Safety). 임의의 파일 쓰기—특히 셸 (shell)이나 언어 서버 (language server) 내에서의 작업—는 권한 상승 (privilege escalation), 악성 코드 주입, 또는 단 한 번의 오류로 src/ 디렉토리를 통째로 날려버릴 위험이 있습니다.
속도 (Speed). 대규모 리포지토리 (repos)의 경우, 전통적인 "전체 트리 (whole tree)" 분석은 비용이 많이 들거나 아예 멈춰버릴 수 있습니다. 합성된 데이터는 I/O 병목 현상을 피할 수 있습니다.
인프라 구축의 용이성 (Easier infra). 웹 에이전트(예: VS Code의 브라우저 샌드박스에서 실행되는 경우)는 보통 디스크 접근 권한이 없는데, 여기에는 타당한 이유가 있습니다. 패치 (patches)는 데이터 블롭 (data blobs) 형태로 전달됩니다.

하지만 이러한 트레이드오프 (tradeoff)는 실제 소프트웨어 자동화에 있어 치명적입니다:

- 모든 TypeScript 파일의 임포트 (imports)를 확인하고, 각 파일에 새로운 타입을 주입한 뒤, 새 페이지를 위해 앱 라우터 (app router)를 업데이트하세요.
+ 붙여넣은 스니펫 (snippet)을 기반으로 추측하세요 — 앱을 망가뜨리지 않을 만큼의 충분한 컨텍스트 (context)가 있기를 바라면서 말이죠.

샌드박스 에이전트는 인상적으로 보이는 코드를 작성할 수는 있지만, 리포지토리 내에서 그 코드를 _검증 (verify)_할 수 없고, 변경 사항을 엔드 투 엔드 (end to end)로 연결할 수 없으며, 변경 후의 빌드 (build)나 테스트 (test)를 실행할 수 없습니다. 실제로 AI가 생성한 모든 패치는 사람이 디버깅하고 연결해야 하는 TODO 목록의 더미가 됩니다.

합성된 컨텍스트의 고통: 샌드박스 에이전트가 한계에 부딪히는 지점

실제 사례를 들어보겠습니다: SaaS 프로젝트에서 결제 통합 (payments integration) 기능을 확장하는 상황입니다. 코드는 다음과 같이 분산되어 있습니다:

components/Billing.tsx
pages/api/stripe.ts
lib/stripeClient.ts
.env.example (새로운 비밀 키를 위해)
README.md (공개 API 변경 후의 문서)

샌드박스 에이전트는 당신이 제공하는 파일들만 볼 수 있습니다. 만약 Billing.tsx만 붙여넣는다면, 에이전트는 API 라우트 (route)나 환경 변수 (env) 파일에 대해 전혀 알지 못합니다.

당신은 수동으로 이 조각들을 이어 붙일 수 있습니다:

"billing"과 관련된 모든 파일을 찾습니다.
해당 파일들(또는 디프 (diffs))을 순서대로 에이전트에 복사하여 붙여넣습니다.
여러 파일에 적용되는 패치 (multi-file patch)를 요청합니다.

하지만 이것은 흐름(flow)이 아니라 마찰(friction)입니다. 결국 인간이 컨텍스트 빌더(context builder)이자 패치 적용자(patch applier)가 됩니다. 그리고 에이전트가 변경한 내용은 일관성 없는 임포트(imports), 이름(names), 타입(types) 등으로 인해 파편화되는 경우가 많습니다. 이것이 현재 세대의 AI CLI에서 복잡한 업그레이드나 리팩터링(refactor)이 중단되는 이유입니다.

진정한 에이전트에게는 실제 코드 — 그리고 코드를 변경할 수 있는 능력이 필요합니다.

OTF의 기본 원칙: 겉모습이 아닌 코드베이스 전체를 전달합니다

모든 OTF 키트는 전체 리포지토리(repo) 형태로 제공됩니다. 즉, 실제 파일 트리(file tree)가 살아있고, 빌드(build)가 가능하며, 프로덕션(production) 환경에 연결되어 있습니다. 클라우드 UI 뒤에 가려진 것도, API 키 뒤에 숨겨진 것도 없으며, 코드를 해석하기 위해 클라우드 측 에이전트가 필요한 것도 없습니다.

진정한 템플릿은 설치 직후 다음과 같은 모습이어야 합니다:

npx otf new saas-dashboard demo-saas
cd demo-saas

...

포함된 구성 요소:

모든 실제 파일 (컴포넌트(components), 라우트(routes), 설정(config), .env.example, 스크립트(scripts))
디자인 토큰(Design tokens): 모든 플랫폼에서 테마를 실제로 변경할 수 있도록 지원
클라우드 배포(cloud deploy), 도메인/TLS, 모바일 빌드(mobile build)를 위한 CLI 와이어링(wiring)
직접 작성된 AI 설정: CLAUDE.md, .cursorrules, 그리고 에이전트를 위한 20개 이상의 프롬프트(prompts)

이 형식이 의미하는 바는 다음과 같습니다. 여러분의 에이전트는 실제 결과물 — 즉, 프로덕션에 존재할 형태 그대로의 리포지토리에 접근할 수 있습니다. 환각된(hallucinated) 경로도, 이상한 구조도, 별도의 글루 코드(glue code)도 필요하지 않습니다.

인트리(in-tree) AI 설정이 핵심인 이유

README.md는 이미 익숙하실 것입니다. OTF는 여기에 더 많은 것을 심어둡니다: CLAUDE.md, .cursorrules, 그리고 파일 시스템 에이전트가 코드와 상호작용하는 방식을 조정하는 AI 지향적 컨벤션(conventions)들입니다.

이를 통해 얻을 수 있는 이점은 무엇인가요?

명확한 작업 파일: 어떤 기능이 존재하는지, 새로운 기능은 어디에 위치해야 하는지, 트리거 문구(trigger phrases), 빌드/테스트/실행 명령어를 정의합니다.
가드레일(Guardrails): 에이전트에게 리포지토리의 형태, 수정 가능한 범위와 불가능한 범위, 업그레이드 가이드를 알려줍니다.
파일 트리 구조에 매핑된 프롬프트: 에이전트는 기능을 확장하는 방법을 추측하는 것이 아니라, 키트에 내장된 제1원칙(first principles)으로부터 작업을 재개합니다.

CLAUDE.md (주요 대상인 Claude 또는 GPT-4o와 같은 대규모 컨텍스트 LLM의 이름을 따서 명명됨)는 설계 의도(design intent), 확장 패턴(extension patterns), 그리고 연결 단계(wiring steps)를 명시합니다. .cursorrules는 코딩 컨벤션(coding conventions), 파일 패턴, 그리고 프로젝트별 린트 규칙(lint rules)을 인코딩합니다.

에이전트에 파일 접근 권한을 연결하면, 에이전트가 이를 자동으로 파악합니다. 그 결과, 다음번 "OAuth 지원 추가" 또는 "다크 모드 추가" 명령은 막연한 추측이 아니라, 실제 근거가 되는 문서(ground-truth docs)에 의해 가이드됩니다.

# CLAUDE.md

## 새로운 결제 제공업체 추가
...

파일 시스템 접근 권한이 연결된 AI 에이전트를 사용한다면, 이러한 지침들은 모든 코드 생성(code-gen) 단계에서 컨텍스트(context)로 전달됩니다. 추측은 줄어들고, 불완전하게 구현된 기능은 감소합니다.

워크플로우: 진정한 확장을 위한 에이전트 연결

이를 구체화해 보겠습니다. 기능을 추가하고 싶고, 당신이 선택한 AI 도구 — Claude Code, Cursor, Lovable 등 무엇이든 — 가 리포지토리 접근 모드(repo access mode)를 지원한다고 가정합니다 (현재 대부분의 도구가 지원합니다).

먼저 당신의 OTF 키트 루트(root)를 제공하는 것으로 시작합니다:

cd ~/dev/demo-saas

# 에이전트 기능이 활성화된 에디터(Cursor, Claude Code 등)에서 리포지토리를 엽니다.
...

에이전트는 다음과 같은 작업을 수행합니다:

파일 트리(routes, 기존 초대 로직 등)를 스캔합니다.
확장 컨벤션(extension conventions)을 위해 CLAUDE.md와 .cursorrules를 읽습니다.
실제 파일을 작성하고, 문서를 업데이트하며, 연결되어 있다면 작성 후 스크립트(post-write scripts)를 실행합니다.

당신은 변경 사항(diff)을 검토(sanity-check)하고, "commit"을 누른 뒤 push합니다. 별도의 접착제(glue) 코드도, 오류가 발생하기 쉬운 컨텍스트 구축 과정도, 드리프트(drift)를 방지하기 위한 수동 테스트도 필요 없습니다.

나중에 더 빠르거나 저렴한 모델 또는 도구를 채택하더라도 아무것도 깨지지 않습니다: OTF의 리포지토리 내 설정(in-repo config)과 컨벤션은 파일 시스템을 다룰 수 있는 모든 에이전트에게 동일한 레일(rails)을 제공합니다.

이것이 코드 배포(shipping code)에 주는 이점

가장 큰 승리는 다음과 같습니다: 당신의 코딩 에이전트는 단순한 제안 상자(suggestion box)가 아니라, 확장(extension) 도구가 됩니다. 이는 다음을 의미합니다:

실제 기능이 단순히 마크다운(Markdown)으로 읽히는 것에 그치지 않고, 배포되고, 검증되며, 커밋될 수 있습니다.
업그레이드와 리팩터링(refactors)이 채팅창에 보이는 부분뿐만 아니라 필요한 모든 파일에 적용됩니다.
에이전트가 실제 환경을 보고 업데이트하기 때문에, 문서와 빌드 스크립트가 동기화된 상태를 유지합니다.

에이전트의 역량이 향상됨에 따라 OTF 키트도 함께 확장됩니다. 지속 가능한 계약은 다음과 같습니다: AI 에이전트가 당신의 실제 파일을 읽고 쓸 수 있다면, 키트는 에이전트를 차단하거나, 제한하거나, 혼란스럽게 만들지 않고 즉시 작업을 시작할 수 있습니다.

시작 앱이 단순한 복사-붙여넣기 코드이거나 클라우드상의 장난감 수준이라면 이는 불가능합니다. 이는 경계를 이동함으로써만 가능해집니다. 즉, 에이전트에게는 파일 시스템 (file-system) 접근 권한이 필요하며, 템플릿은 겉모습(facade)이 아닌 코드베이스 (codebase)여야 합니다.

[[IMG: repo agent interaction diagram]]

OTF는 AI 도구의 급격한 변화 속에서도 변하지 않는 안정적인 계약입니다

매주 새로운 코딩 에이전트가 출시되며, 각 에이전트는 저마다의 독특한 특성, 컨텍스트 제한 (context limits), 그리고 독자적인 CLI를 가지고 있습니다.

변하지 않는 안정적인 계층은 다음과 같습니다: 파일 형태로 배포되는 실제 코드베이스이며, 어떤 에이전트에게도 기능을 올바른 방식으로 연결하고 확장하는 방법을 알려줄 수 있는 인트리 구성 (in-tree config)을 포함합니다. OTF는 매번 그 계약을 전달합니다.

결과적으로:

이번 시즌에 승리하는 AI 코딩 도구가 무엇이든 사용하세요 — Cursor, Claude Code, Lovable, Rork, 클라우드 기반이든 로컬 기반이든 상관없습니다.
OTF 키트는 준비되어 있습니다: 파일 시스템 에이전트를 코드베이스로 지정하기만 하면, 컨텍스트 (context)가 즉시 확보되며, 확장은 가이드에 따라 재현 가능하게 이루어집니다.
키트가 특정 도구나 블랙박스 API (black-box API)에 종속되지 않기 때문에