Kiroignore

목표

.kiroignore 파일로 Kiro가 읽을 수 없는 파일을 지정해, 자격 증명·비밀·비공개 콘텐츠를 에이전트 컨텍스트 밖에 두는 방법을 파악합니다.

개념

.kiroignore 파일은 Kiro가 워크스페이스의 특정 파일을 읽지 못하게 막습니다. 익숙한 gitignore 문법으로 비공개로 유지할 파일(자격 증명, 비밀, 에이전트 컨텍스트에서 빼고 싶은 내용)의 패턴을 정의합니다.

지원되는 곳에서는 ignore 패턴이 에이전트의 도구 전반에 적용됩니다 — 차단된 파일은 어떤 도구가 읽으려 해도 차단됩니다. 파일/텍스트 검색 결과를 반환하기 전에 Kiro는 각 결과를 읽기 권한과 ignore 규칙에 대조하며, ignore되었거나 읽을 수 없는 파일의 경로와 매칭 내용은 검색 결과에 나타나지 않습니다.

.kiroignore를 쓰는 이유:

• Security — 자격 증명, API key 등 민감 데이터가 담긴 파일 접근 방지
• Privacy — 기밀 정보를 AI 상호작용에서 제외
• Compliance — 공유되면 안 되는 파일에 Kiro가 접근하지 않도록 보장
• Focus — 큰 파일이나 빌드 산출물을 제외해 컨텍스트를 관련 있게 유지

활용

Capability	IDE	CLI	Web	Mobile
Workspace .kiroignore	✓	V3	—	—
Global ignore file (~/.kiro/settings/kiroignore)	✓	V3	—	—

IDE는 지원되는 에이전트 도구 전반에 .kiroignore를 강제합니다. CLI V3에서는 workspace .kiroignore 또는 global ignore 파일이 매칭 파일을 직접 읽기에서 차단하고 콘텐츠·파일명 검색 결과에서 걸러냅니다. Web 지원은 아직 없습니다.

설정과 사용 예시

Workspace ignore

특정 프로젝트의 파일을 제외하려면 프로젝트 루트(또는 하위 디렉터리)에 .kiroignore 파일을 만들고, 제외할 파일의 패턴을 추가합니다.

# Secrets and credentials
.env
.env.*
!.env.example
*.pem
*.key

# Private directories
secrets/
private/

Kiro는 패턴에 매칭되는 파일을 건너뜁니다. .gitignore처럼 하위 디렉터리에도 .kiroignore를 두어 상위 패턴을 재정의하거나 확장할 수 있고, 하위 디렉터리 ignore 파일의 패턴이 그 디렉터리 안의 파일에 우선합니다.

IDE는 Agent Ignore Files 설정(kiroAgent.agentIgnoreFiles)에서 ignore 파일명을 읽습니다. Settings(Cmd+, / Ctrl+,)에서 Agent Ignore Files를 검색해 배열에 .kiroignore를 추가하세요. 이 설정은 파일명 배열을 받습니다.

• 여러 ignore 파일 타입 동시 사용: [".gitignore", ".kiroignore"]
• workspace 수준 ignore 파일 비활성화: []

Global ignore files

Kiro는 아래 global ignore 파일이 있으면 자동으로 따릅니다 — 별도 설정이 필요 없습니다.

• ~/.kiro/settings/kiroignore — 전역 Kiro ignore 패턴
• Git의 global ignore 파일(git config의 core.excludesfile) — git 저장소에서만 적용

패턴 문법

.kiroignore는 표준 gitignore 문법을 씁니다.

패턴	효과
file.txt	특정 파일 ignore
*.log	확장자로 ignore
folder/	디렉터리 ignore
**/temp	모든 하위 디렉터리에서 ignore
!keep.txt	ignore 안 함(negation)

ℹ️ 참고

상위 디렉터리가 제외되면 그 안의 파일을 다시 포함할 수 없습니다. 예를 들어 secrets/를 ignore하면 !secrets/public.txt를 추가해도 동작하지 않습니다. 디렉터리에서 특정 파일만 포함하려면 전체 디렉터리를 제외하는 대신 더 구체적인 패턴을 쓰세요.

빌드 산출물·데이터 파일 제외 예시:

# Build outputs
dist/
build/
.next/

# Data files
*.sql
*.dump
data/exports/

해볼 것

💡 연습용 프로젝트에서 수행하세요. 자격 증명과 비밀부터 보호하는 것이 우선순위가 가장 높습니다.

1단계: ignore 파일 만들기

프로젝트 루트에 .kiroignore를 만들고 위 Workspace ignore 예시의 .env·*.pem 패턴을 넣습니다. CLI를 쓴다면 V3 로컬 세션인지 확인하세요 — workspace .kiroignore는 V3에서 적용됩니다.

2단계: 차단 확인하기

Kiro에게 ignore된 파일(예: .env)을 읽어 달라고 요청합니다. Kiro가 접근이 차단되었음을 알리는지 확인합니다.

3단계: 검색에서 사라지는지 확인하기

ignore된 파일에만 있는 문자열로 콘텐츠 검색을 시켜, 해당 경로와 매칭 내용이 검색 결과에 나타나지 않는지 관찰합니다.

모범 사례

• 왜 ignore했는지 주석으로 문서화 — 팀원에게 도움
• 패턴 테스트: Kiro에게 ignore된 파일을 읽어 달라고 해 차단 여부 확인
• 프로젝트 구조가 바뀌면 패턴을 주기적으로 검토
• 일관성을 위해 전역 패턴을 팀과 조율

더 알아보기

• Kiroignore
• Permissions — 읽기 권한과 ignore 규칙이 함께 검색 결과를 거르는 방식(fs_read deny 규칙)
• Kiro 동작 원리 — kiroignore가 turn의 3단계(도구 호출 검사)에 붙는 위치
• Hooks — 에이전트 루프 주변 자동화와의 조합

---

출처: kiro.dev 공식 문서 "Kiroignore" (2026-10-26 확인).