.kiroignore

Kiro가 워크스페이스 안에서 특정 파일을 절대 읽지 못하도록 막는 규칙 파일입니다. 자격 증명, 비밀 키, 외부에 노출돼서는 안 되는 데이터를 에이전트의 컨텍스트에서 제외할 때 사용합니다.

왜 .kiroignore가 필요한가

.kiroignore는 .gitignore와 동일한 패턴 문법을 따르며, Kiro 에이전트가 어떤 파일을 읽지 않을지 명시적으로 선언합니다. 다음과 같은 상황에서 유용합니다.

워크스페이스에 적용하기

특정 프로젝트에서만 동작하는 ignore 파일을 만들고 Kiro에게 인식시키는 절차입니다.

  1. 프로젝트 루트(또는 임의의 하위 디렉터리)에 .kiroignore 파일을 생성합니다.
  2. 제외하려는 파일 패턴을 작성합니다. 
    # Secrets and credentials
.env
.env.*
!.env.example
*.pem
*.key

# Private directories
secrets/
private/
  3. Settings를 엽니다. macOS에서는 Cmd+,, Windows/Linux에서는 Ctrl+,입니다.
  4. 검색창에 Agent Ignore Files를 입력합니다. 실제 설정 키는 kiroAgent.agentIgnoreFiles입니다.
  5. 해당 배열에 .kiroignore를 추가합니다.

처음에는 자격 증명·비밀 정보부터 막고, 프로젝트가 커지면서 데이터 디렉터리나 빌드 산출물로 패턴을 점진적으로 확장하는 방식이 안정적입니다.

설정 옵션

kiroAgent.agentIgnoreFiles는 파일 이름 배열을 값으로 받습니다.

하위 디렉터리 ignore 파일

.gitignore와 마찬가지로, 하위 디렉터리에도 별도의 .kiroignore를 둘 수 있습니다. 해당 디렉터리 안에서는 하위 ignore 파일의 규칙이 상위 규칙보다 우선합니다.

전역 ignore 파일

아래 위치의 파일은 별도 설정 없이 Kiro가 자동으로 인식합니다.

패턴 문법

표준 gitignore 문법을 그대로 사용할 수 있습니다.

패턴의미
file.txt특정 파일 하나를 제외
*.log확장자 단위로 제외
folder/디렉터리 전체 제외
**/temp모든 하위 경로의 일치 항목 제외
!keep.txt다시 포함(부정 규칙)

이미 제외된 상위 디렉터리 안의 파일은 부정 규칙으로 되살릴 수 없습니다. 예컨대 secrets/를 통째로 막은 상태에서 !secrets/public.txt를 적어도 효과가 없습니다. 이런 경우에는 처음부터 더 좁은 패턴으로 작성하세요.

실제 예시

API 키와 시크릿 차단

# Environment files with credentials
.env
.env.local
.env.production

# Keep the template accessible
!.env.example

# Certificate and key files
*.pem
*.key
*.p12
credentials/

빌드 산출물과 데이터 파일 제외

# Build outputs
dist/
build/
.next/

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

팀 단위 컴플라이언스 설정

# Customer data directories
customer-data/
pii/

# Audit and compliance docs
compliance/internal/
audit-reports/

에이전트의 접근 정책이 버전 관리 정책과 달라야 하거나, git에는 추적되지만 Kiro에는 보여주고 싶지 않은 파일이 있을 때 .kiroignore가 특히 유용합니다.

운영 팁