Agent Context Loader
개요
프로젝트 계층 구조 전반에서 AGENTS.md 파일을 자동으로 검색하고 로드하여 AI 코딩 에이전트에 제공합니다. 이 스킬은 현재 작업 공간과 상위 디렉토리를 스캔하여 에이전트 명령 파일을 찾은 다음, 그 내용을 표면화하여 활성 에이전트 세션이 전체 운영 컨텍스트를 가질 수 있도록 합니다.
전제 조건
- 모든 디렉토리 깊이에 하나 이상의
AGENTS.md파일이 포함된 프로젝트 작업 공간 - 디렉토리 트리를 탐색할 수 있는 읽기 및 Glob 권한
- 여러 후보 파일이 있을 때 파일 내용을 검색하기 위한 Grep 액세스 권한
지침
- 현재 작업 디렉토리와 모든 상위 디렉토리(파일 시스템 루트 또는 저장소 루트까지)에서
AGENTS.md또는agents.md라는 파일을 스캔합니다. - 현재 작업 공간의 하위 디렉토리에서 서브 프로젝트 또는 모듈에 적용될 수 있는 추가
AGENTS.md파일을 검색합니다. - 로드 순서를 결정합니다. 저장소 루트에 가까운 파일이 먼저 로드되고(전역 컨텍스트), 더 깊은 디렉토리의 파일이 나중에 로드됩니다(재정의 또는 보충).
- 발견된 각
AGENTS.md파일을 읽고 명령 블록, 워크플로우 정의 및 제약 조건 선언을 추출합니다. - 명령을 통합 컨텍스트로 병합하고, 수준 간 충돌(예: 하위 디렉토리 에이전트가 루트 수준 규칙을 재정의)을 기록합니다.
- 로드된 컨텍스트를 구조화된 요약(소스 파일 경로, 명령 수, 감지된 충돌)으로 제시합니다.
- 후속 활성화에서 불필요한 파일 시스템 스캔을 방지하기 위해 현재 세션의 검색 결과를 캐싱합니다.
출력
- 디렉토리 깊이와 함께 발견된
AGENTS.md파일 경로의 정렬된 목록 - 모든 발견된 에이전트 컨텍스트를 결합한 병합된 명령 집합
- 수준 간 모순되는 지시 사항을 강조하는 충돌 보고서
- 결과가 새 것인지 재사용된 것인지 나타내는 세션 캐시 상태
오류 처리
| 오류 | 원인 | 해결 방법 |
|---|---|---|
AGENTS.md 없음 | 작업 공간에 에이전트 명령 파일이 없음 | 올바른 작업 디렉토리 확인; 프로젝트 루트에 AGENTS.md 생성 필요 |
| 디렉토리 탐색 권한 거부됨 | 작업 공간 위의 제한된 상위 디렉토리 | 스캔 깊이를 저장소 루트( .git/ 존재로 감지)로 제한 |
| 순환 심볼릭 링크 감지됨 | 심볼릭 링크된 디렉토리가 무한 탐색 루프 생성 | 스캔 중 심볼릭 링크된 디렉토리 건너뛰기; 심볼릭 링크 경로와 함께 경고 기록 |
| 수준 간 명령 충돌 | 하위 디렉토리 AGENTS.md가 루트 수준 파일과 모순됨 | 출력에서 충돌 표시; 기본적으로 더 구체적인(더 깊은) 명령 적용 |
| 파일 인코딩 오류 | AGENTS.md가 UTF-8이 아닌 인코딩 사용 | latin-1 대체 시도; 파일 경로 및 인코딩 문제 보고 |
예시
예시 1: 패키지별 에이전트 지침이 있는 모노레포
- 구조: 루트
AGENTS.md는 전역 규칙을 설정하고,packages/api/AGENTS.md는 API별 도구 규칙을 추가합니다. - 결과: 두 파일이 순서대로 로드됩니다. API별 규칙은 충돌 없이 전역 컨텍스트를 보완합니다.
예시 2: 충돌하는 커밋 정책이 있는 중첩 작업 공간
- 구조: 루트
AGENTS.md는 "항상 커밋 서명"을 지시하고,services/legacy/AGENTS.md는 "커밋 서명 건너뛰기"를 지시합니다. - 결과: 충돌이 감지되고 보고됩니다. 더 깊은(레거시) 지시 사항이 적용되며 재정의에 대한 경고가 표시됩니다.
예시 3: 에이전트 파일이 없는 첫 설정
- 구조:
AGENTS.md가 전혀 없는 갓 클론된 저장소. - 결과: 스캔 완료 시 파일이 0개 발견됨. 출력에는 저장소 루트에 최소 템플릿으로
AGENTS.md를 생성하라는 제안이 포함됩니다.
리소스
- Claude Code AGENTS.md 사양: https://docs.anthropic.com/en/docs/agents
- 에이전트 구성을 위한 모노레포 작업 공간 패턴: https://docs.anthropic.com/en/docs/claude-code
- 계층적 구성 로드를 위한 파일 검색 모범 사례