딥 이니트(Deep Init) 스킬
전체 코드베이스에 포괄적이고 계층적인 AGENTS.md 문서를 생성합니다.
핵심 개념
AGENTS.md 파일은 AI가 읽을 수 있는 문서 역할을 하며, 에이전트가 다음을 이해하는 데 도움을 줍니다.
- 각 디렉토리가 무엇을 포함하는지
- 컴포넌트들이 서로 어떻게 관련되는지
- 해당 영역에서 작업하기 위한 특별 지침
- 의존성 및 관계
계층적 태깅 시스템
모든 AGENTS.md(루트 제외)는 부모 참조 태그를 포함합니다.
<!-- Parent: ../AGENTS.md -->
이를 통해 탐색 가능한 계층 구조가 생성됩니다.
/AGENTS.md ← 루트 (부모 태그 없음)
├── src/AGENTS.md ← <!-- Parent: ../AGENTS.md -->
│ ├── src/components/AGENTS.md ← <!-- Parent: ../AGENTS.md -->
│ └── src/utils/AGENTS.md ← <!-- Parent: ../AGENTS.md -->
└── docs/AGENTS.md ← <!-- Parent: ../AGENTS.md -->
AGENTS.md 템플릿
<!-- Parent: {relative_path_to_parent}/AGENTS.md -->
<!-- Generated: {timestamp} | Updated: {timestamp} -->
# {디렉토리 이름}
## 목적
{이 디렉토리가 포함하는 내용과 그 역할에 대한 한 단락 설명}
## 주요 파일
{각 중요한 파일을 한 줄 설명과 함께 나열}
| 파일 | 설명 |
|------|------|
| `file.ts` | 용도에 대한 간략한 설명 |
## 하위 디렉토리
{각 하위 디렉토리를 간략한 목적과 함께 나열}
| 디렉토리 | 목적 |
|-----------|---------|
| `subdir/` | 포함하는 내용 (`subdir/AGENTS.md` 참조) |
## AI 에이전트를 위한 정보
### 이 디렉토리에서 작업하기
{여기서 파일을 수정하는 AI 에이전트를 위한 특별 지침}
### 테스트 요구 사항
{이 디렉토리의 변경 사항을 테스트하는 방법}
### 일반적인 패턴
{여기서 사용되는 코드 패턴 또는 규칙}
## 의존성
### 내부
{이 디렉토리가 의존하는 코드베이스의 다른 부분 참조}
### 외부
{사용되는 주요 외부 패키지/라이브러리}
<!-- MANUAL: 이 줄 아래에 수동으로 추가된 메모는 재생성 시 보존됩니다 -->
실행 워크플로우
1단계: 디렉토리 구조 매핑
Task(subagent_type="explore", model="haiku",
prompt="모든 디렉토리를 재귀적으로 나열하세요. 제외: node_modules, .git, dist, build, __pycache__, .venv, coverage, .next, .nuxt")
2단계: 작업 계획 수립
각 디렉토리에 대한 할 일 항목을 깊이 수준별로 생성합니다.
레벨 0: / (루트)
레벨 1: /src, /docs, /tests
레벨 2: /src/components, /src/utils, /docs/api
...
3단계: 레벨별로 생성
중요: 부모 참조가 유효하도록 하위 레벨보다 먼저 상위 레벨을 생성하세요.
각 디렉토리에 대해:
- 디렉토리의 모든 파일 읽기
- 목적과 관계 분석
- AGENTS.md 콘텐츠 생성
- 올바른 부모 참조로 파일 쓰기
4단계: 비교 및 업데이트 (파일이 이미 존재하는 경우)
AGENTS.md가 이미 존재하는 경우:
- 기존 콘텐츠 읽기
- 섹션 식별:
- 자동 생성된 섹션 (업데이트 가능)
- 수동 섹션 (
<!-- MANUAL -->보존)
- 비교:
- 새 파일이 추가되었는가?
- 파일이 제거되었는가?
- 구조가 변경되었는가?
- 병합:
- 자동 생성된 콘텐츠 업데이트
- 수동 주석 보존
- 타임스탬프 업데이트
5단계: 계층 구조 검증
생성 후, 유효성 검사를 실행합니다.
| 검사 | 확인 방법 | 수정 조치 |
|---|---|---|
| 부모 참조 확인 | 각 AGENTS.md를 읽고 <!-- Parent: --> 경로가 존재하는지 확인 | 경로 수정 또는 고아 파일 제거 |
| 고아 AGENTS.md 없음 | AGENTS.md 위치와 디렉토리 구조 비교 | 고아 파일 삭제 |
| 완전성 | 모든 디렉토리 나열, AGENTS.md 확인 | 누락된 파일 생성 |
| 타임스탬프 최신 | <!-- Generated: --> 날짜 확인 | 오래된 파일 재생성 |
검증 스크립트 패턴:
# 모든 AGENTS.md 파일 찾기
find . -name "AGENTS.md" -type f
# 부모 참조 확인
grep -r "<!-- Parent:" --include="AGENTS.md" .
스마트 위임
| 작업 | 에이전트 |
|---|---|
| 디렉토리 매핑 | explore |
| 파일 분석 | architect |
| 콘텐츠 생성 | writer |
| AGENTS.md 쓰기 | writer |
빈 디렉토리 처리
비어 있거나 거의 비어 있는 디렉토리를 만난 경우:
| 조건 | 조치 |
|---|---|
| 파일 없음, 하위 디렉토리 없음 | 건너뛰기 - AGENTS.md를 만들지 않음 |
| 파일 없음, 하위 디렉토리 있음 | 하위 디렉토리 목록만 포함하는 최소 AGENTS.md 생성 |
| 생성된 파일만 있음 (*.min.js, *.map) | 건너뛰거나 최소 AGENTS.md 생성 |
| 설정 파일만 있음 | 설정 목적을 설명하는 AGENTS.md 생성 |
디렉토리 전용 컨테이너를 위한 최소 AGENTS.md 예시:
<!-- Parent: ../AGENTS.md -->
# {디렉토리 이름}
## 목적
관련 모듈을 구성하기 위한 컨테이너 디렉토리.
## 하위 디렉토리
| 디렉토리 | 목적 |
|-----------|---------|
| `subdir/` | 설명 (`subdir/AGENTS.md` 참조) |
병렬화 규칙
- 동일 레벨 디렉토리: 병렬로 처리
- 다른 레벨: 순차적 (상위 우선)
- 큰 디렉토리: 디렉토리별로 전담 에이전트 생성
- 작은 디렉토리: 여러 개를 하나의 에이전트로 일괄 처리
품질 기준
반드시 포함해야 할 사항
- 정확한 파일 설명
- 올바른 부모 참조
- 하위 디렉토리 링크
- AI 에이전트 지침
반드시 피해야 할 사항
- 일반적인 보일러플레이트
- 잘못된 파일 이름
- 깨진 부모 참조
- 중요한 파일 누락
예시 출력
루트 AGENTS.md
<!-- Generated: 2024-01-15 | Updated: 2024-01-15 -->
# my-project
## 목적
실시간 협업 기능을 갖춘 사용자 작업 관리 웹 애플리케이션.
## 주요 파일
| 파일 | 설명 |
|------|------|
| `package.json` | 프로젝트 의존성 및 스크립트 |
| `tsconfig.json` | TypeScript 설정 |
| `.env.example` | 환경 변수 템플릿 |
## 하위 디렉토리
| 디렉토리 | 목적 |
|-----------|---------|
| `src/` | 애플리케이션 소스 코드 (`src/AGENTS.md` 참조) |
| `docs/` | 문서 (`docs/AGENTS.md` 참조) |
| `tests/` | 테스트 스위트 (`tests/AGENTS.md` 참조) |
## AI 에이전트를 위한 정보
### 이 디렉토리에서 작업하기
- 프로젝트 매니페스트를 수정한 후 항상 의존성을 설치하세요.
- TypeScript 엄격 모드를 사용하세요.
- ESLint 규칙을 따르세요.
### 테스트 요구 사항
- 커밋 전에 테스트를 실행하세요.
- 80% 이상의 커버리지를 보장하세요.
### 일반적인 패턴
- 배럴 내보내기(index.ts)를 사용하세요.
- 함수형 컴포넌트를 선호하세요.
## 의존성
### 외부
- React 18.x - UI 프레임워크
- TypeScript 5.x - 타입 안전성
- Vite - 빌드 도구
<!-- MANUAL: 사용자 정의 프로젝트 노트는 아래에 추가할 수 있습니다 -->
중첩 AGENTS.md
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2024-01-15 | Updated: 2024-01-15 -->
# components
## 목적
기능과 복잡성에 따라 구성된 재사용 가능한 React 컴포넌트.
## 주요 파일
| 파일 | 설명 |
|------|------|
| `index.ts` | 모든 컴포넌트를 위한 배럴 내보내기 |
| `Button.tsx` | 기본 버튼 컴포넌트 |
| `Modal.tsx` | 모달 다이얼로그 컴포넌트 |
## 하위 디렉토리
| 디렉토리 | 목적 |
|-----------|---------|
| `forms/` | 폼 관련 컴포넌트 (`forms/AGENTS.md` 참조) |
| `layout/` | 레이아웃 컴포넌트 (`layout/AGENTS.md` 참조) |
## AI 에이전트를 위한 정보
### 이 디렉토리에서 작업하기
- 각 컴포넌트는 자체 파일을 가집니다.
- 스타일링에 CSS 모듈을 사용하세요.
- index.ts를 통해 내보내세요.
### 테스트 요구 사항
- 단위 테스트는 `__tests__/` 하위 디렉토리에 있습니다.
- React Testing Library를 사용하세요.
### 일반적인 패턴
- Props 인터페이스는 컴포넌트 위에 정의됩니다.
- DOM을 노출하는 컴포넌트에는 forwardRef를 사용하세요.
## 의존성
### 내부
- `src/hooks/` - 컴포넌트가 사용하는 커스텀 훅
- `src/utils/` - 유틸리티 함수
### 외부
- `clsx` - 조건부 클래스 이름
- `lucide-react` - 아이콘
<!-- MANUAL: -->
업데이트 모드 트리거
AGENTS.md 파일이 있는 기존 코드베이스에서 실행할 때:
- 먼저 기존 파일 탐지
- 기존 콘텐츠 읽기 및 파싱
- 현재 디렉토리 상태 분석
- 기존과 현재 상태 간의 차이 생성
- 수동 섹션을 보존하면서 업데이트 적용
성능 고려 사항
- 디렉토리 목록 캐시 - 동일한 디렉토리를 재스캔하지 않음
- 작은 디렉토리 일괄 처리 - 여러 개를 한 번에 처리
- 변경되지 않은 경우 건너뛰기 - 디렉토리가 변경되지 않은 경우 재생성 건너뛰기
- 병렬 쓰기 - 여러 에이전트가 동시에 다른 파일에 쓰기