파일 무시

파일 무시 (Ignoring files)

.agentsignore 파일로 에이전트가 보지 못하게 할 파일을 숨겨요, .gitignore 와 같은 구문을 사용해요.

출처: 문서

본문

개요 (Overview)

프로젝트에 .agentsignore 파일을 두면 에이전트가 나열된 경로를 보지 못하게 돼요. 일치하는 파일은 디렉터리 목록과 검색에서 사라지고, 그것들에 대한 읽기·쓰기·편집은 거부돼요.

# .agentsignore
secrets.env
*.key
.env.*
build/
docs/**/*.draft.md
!public.key

구성할 것이 없어요. 파일의 존재 자체가 선택(opt-in)이며, filesystem toolset이 자동으로 인식해요.

구문 (Syntax)

구문은 .gitignore 구문과 같아요 — git이 사용하는 것과 같은 라이브러리로 파싱되므로, 패턴이 .gitignore 및 .dockerignore 와 동일하게 동작해요:

Pattern	Matches
`secrets.env`	어떤 깊이에서든 그 이름 (`secrets.env`, `config/secrets.env`)
`/secrets.env`	프로젝트 루트에서만 그 이름
`*.key`	확장자가 그런 어떤 파일
`build/`	그 디렉터리와 그 아래 모든 것
`docs/*/.draft.md`	`**` 를 통한 중첩 일치
`!public.key`	이전 패턴이 제외한 경로를 다시 포함
`# comment`	주석은 무시되고 빈 줄도 마찬가지

파일이 발견되는 위치 (Where the file is found)

작업 디렉터리에서 그 위로 가장 가까운 .agentsignore 가 사용되므로, 하위 디렉터리에서 실행을 시작해도 프로젝트의 파일이 적용돼요. 패턴은 파일이 있는 디렉터리에 고정(anchor)되는데, git이 .gitignore 가 있는 디렉터리에 고정하는 것과 정확히 같아요.

.gitignore 와 달리 git 저장소는 필요 없어요 — .agentsignore 는 어떤 디렉터리에서든 동작해요.

영향 (What it affects)

Behaviour	Effect
`list_directory`, `directory_tree`	일치하는 항목이 생략됨
`search_files_content`	일치하는 파일이 건너뛰어짐
`read_file`, `read_multiple_files`	거부됨
`write_file`, `edit_file`	거부됨, 아직 존재하지 않는 파일도 포함
`create_directory`, `remove_directory`	거부됨
`permissions`	일치하는 deny 규칙이 자동으로 파생되어 `/permissions` 가 그것들을 표시

경로는 일치 전에 해석돼요 — 심볼릭 링크, ./ 접두사, .. 세그먼트가 모두 정규화되어, 무시된 파일은 다르게 표기해서 도달할 수 없어요. .agentsignore 파일 자체는 항상 숨겨져요: 그것은 막아두는 것들을 나열하므로, 에이전트에게 넘기면 무엇을 찾아야 할지 지도가 되기 때문이에요.

Note .agentsignore 는 filesystem toolset의 ignore_vcs 옵션과 독립적이에요. ignore_vcs: false 로 설정하면 .gitignore 필터링이 꺼지지만 .agentsignore 항목은 숨겨진 채로 있어요.

.gitignore와의 관계 (Relationship to .gitignore)

둘은 별개이며, 하는 일의 양이 달라요.

.gitignore 는 기본적으로(ignore_vcs) 존중되지만, 단지 표시 필터일 뿐이에요: gitignore된 파일은 목록과 검색에서 숨겨지지만 read_file 은 여전히 열어요. 비밀이라기보다 잡음인 빌드 출력에는 그게 적절해요.

.agentsignore 는 에이전트가 아예 가져선 안 되는 콘텐츠를 위한 것이므로 읽기와 쓰기도 막아요. 잡음에는 .gitignore, 시크릿에는 .agentsignore 를 사용하세요.

한계 (Limits)

Warning .agentsignore 는 filesystem toolset을 관장해요. 샌드박스가 아니에요. shell toolset이 있는 에이전트는 여전히 cat secrets.env 를 실행할 수 있어요, 셸이 toolset이 검사하지 않는 명령을 실행하기 때문이에요. 이것은 lsp 처럼 자체적으로 파일시스템에 닿는 어떤 toolset에도 적용돼요. .agentsignore 를 민감한 파일을 에이전트의 시야와 컨텍스트에서 멀리 유지하는 강력한 기본값으로 취급하세요 — 적극적으로 도달하려는 에이전트에 대한 경계로는 아니에요. 진짜 경계가 필요하면 shell 을 제한하는 permissions와 결합하거나, 샌드박스 모드에서 실행하세요. 파생된 권한 규칙은 같은 이유로 최선(best-effort)이에요: 권한 패턴은 모델이 쓴 대로 인자 문자열과 일치하며, 먼저 해석하지 않아요. 그래서 ./secrets.env 는 secrets.env 용으로 작성된 규칙을 빠져나갈 수 있어요. filesystem toolset의 자체 검사는 먼저 경로를 해석하는 부분이며, 실제로 강제하는 부분이에요.

예제 (Example)

# .agentsignore

# Secrets
.env
.env.*
secrets.env
*.pem
*.key
!public.key # this one is safe to read

# Credentials directories
.aws/
.ssh/

# Large build output the agent doesn't need
build/
dist/
node_modules/