스킬: codebase-orient
목적
비사소한 작업을 수행하기 전에 Claude를 현재 저장소 상태에 맞게 지향시킵니다. docs/ai/에 고정된, 출처가 명확한 4개 산출물 패키지를 생성하거나 동기화합니다. 소스 코드와 프로젝트 구성이 권위 있는 출처로 남습니다.
이 스킬을 사용해야 하는 경우
이 스킬을 사용해야 하는 경우
- 새롭거나 익숙하지 않은 저장소에 진입할 때
- 저장소에서 의미 있는 시간을 보낸 후 새로운 세션을 시작할 때
- 광범위하거나 다중 파일 구현 작업 전
- 리팩토링, 정리, 아키텍처 계획 또는 에이전트 인수인계 전
- 라우트, 스키마, 인증, 배포, 구성 또는 관리자 영역과 같은 구조적 변경 후
docs/ai/가 없거나, 오래되었거나, 불완전하거나, 내부적으로 일관성이 없을 때- 저장소 구조, 변경 영역, 배포 대상, 인증 동작, 관리자 라우트, 명령어 또는 테스트 형태가 명확하지 않을 때
- 에이전트가
docs/ai/또는 그 근처에 이미 있는 내용을 재발견하는 데 상당한 컨텍스트를 소비할 때 - 사용자가 "스캔", "지향", "이해", "매핑", "검토", "감사", "조사", "익히기" 또는 "시작하기 전에"라고 말할 때마다
이 스킬을 건너뛰어야 하는 경우
- 단일 파일에 대한 작고, 국지적이며, 알려진 편집을 할 때
- 관련 파일과 변경 사항이 이미 명확한 단일 파일 버그를 수정할 때
- 복사 전용 또는 문자열 전용 변경을 할 때
- 작업이 현재 컨텍스트에서 이미 확인된 파일로 엄격하게 범위가 지정된 경우
docs/ai/가 방금 새로 고쳐졌고 작업이 전체 지향 패스를 필요로 할 정도로 넓지 않은 경우
토큰 인식 사용 지침
docs/ai/는 지향 캐시입니다. 새로운 캐시는 세션 및 에이전트 인수인계 전반에 걸쳐 반복적인 저장소 발견 토큰 비용을 줄여줍니다.
docs/ai/가 최신이고 완전한 경우: 컨텍스트로 읽고 진행하십시오. 지향을 다시 실행하지 마십시오.docs/ai/가 오래되었거나 없는 경우: 스킬을 실행하여 캐시를 새로 고치십시오. 선불 토큰 비용은 앞으로의 작업에 걸쳐 분할 상환됩니다.- 작업이 아주 작고 대상 파일이 이미 알려진 경우: 지향을 건너뛰십시오. 대신 대상 읽기를 사용하십시오.
- 에이전트가
docs/ai/가 이미 캡처한 내용을 재발견하는 데 많은 토큰을 소비할 경우: 캐시를 새로 고치십시오.
지향을 건너뛰고 구조를 추측함으로써 토큰을 절약하지 마십시오. 광범위한 저장소 발견이 반복되거나 비용이 많이 드는 경우 대신 캐시를 새로 고치십시오.
지향 중 하드 규칙
- 애플리케이션 또는 소스 코드를 수정하지 마십시오.
- 리팩토링하지 마십시오.
- 커밋하지 마십시오.
- 주장을 작성하기 전에 소스 코드에 대해 확인하십시오.
- 모든 의미 있는 주장에 신뢰도 레이블을 표시하십시오.
정규 모드와 dry-run 모드
정규 모드(기본값 - 사용자가 지정하지 않은 경우 사용):
- 소스 파일을 읽어 작업과 관련된 작은 불확실성을 자동으로 해결합니다.
- 깨끗한 저장소에서 처음 사용할 때 전체 패키지를 생성합니다.
- 정확히 현재 상태와 일치하는 깨끗한 패키지를 다시 작성하지 않고 재사용합니다.
- 새로 고침 또는 동기화에 대한 불특정 요청을 전체 동기화로 처리합니다.
- 마지막에 변경된 사항을 보고합니다.
Dry-run / 보고 전용 모드(사용자가 "dry-run", "report only", "don't write", "propose changes first", "audit only", "no writes" 등과 같이 말할 때 사용):
- 제안된 변경 사항을 검사하고 수집합니다.
docs/ai/에 대한 제안된 편집 내용을 쓰지 않고 보고합니다.- 쓰기 전에 명시적인 승인을 기다립니다.
모드가 지정되지 않은 경우 기본값은 정규 모드입니다.
수명 주기 및 쓰기 안전
- 명시적 새로 고침: 정확히 현재 상태와 일치하는 패키지가 발견된 후 사용자가 명시적으로 요청한 경우에만 새로 고치거나 동기화합니다.
- 범위 지정 새로 고침: 명시적 사용자 범위와 그 직접 종속성을 따릅니다. 패키지 전체의 전체 스냅샷을 진행하거나 주장하지 않고 범위 지정 적용 범위를 기록합니다. 전체 패키지가 존재하기 전에 부분 지원 패키지를 생성하지 마십시오.
- 레거시 채택:
ORIENTATION_STATE.json이 없는 Markdown 아티팩트는 레거시 자료입니다. 검사하지만, 매니페스트를 쓰거나 변경하기 전에 명시적인 승인을 받으십시오. 승인 후 소스에서 동기화하십시오. - 더티 트리: 커밋되지 않은 작업을 나타내는 상태를 쓰기 전에 더티 스냅샷을 쓸지 아니면 보고만 할지 물어보십시오. 트리 조건을 기록하십시오. 깨끗한 새로 고침이 대체할 때까지 더티로 표시된 상태를 유지하십시오.
- 사용 가능한 Git 기록 없음: 전체 동기화를 수행하고 리비전 비교를 사용할 수 없음을 기록합니다.
- 수동 편집: Orient는 패키지를 소유합니다. 수동으로 편집된 Orient 상태에 대한 병합 또는 보존 동작을 약속하지 마십시오.
신뢰도 레이블
- 사실(Fact): 코드나 문서에서 직접 확인됨
- 강한 추론(Strong inference): 여러 파일에 의해 뒷받침됨
- 약한 추론(Weak inference): 그럴듯하지만 확인되지 않음
- 알 수 없음(Unknown): 편집 전 더 많은 검사가 필요함
주장이 어떻게 확립되었는지 구별하십시오:
- 소스/설정에서 독립적으로 확인됨(independently verified from source/config): 문서가 아닌 실제 소스 또는 설정 파일에 대해 확인된 주장
- 기존 문서에서 상속됨(inherited from existing docs): 독립적인 확인 없이 CLAUDE.md, README 또는 기타 문서에서 가져온 주장
- 상속 후 확인됨(inherited then verified): 문서에서 시작되어 이후 소스에 대해 확인된 주장
- 경로 존재 확인됨(path existence confirmed): 파일이 발견되었지만 읽히지 않음
- 부분 읽기(partial read): 파일의 일부가 검사되었으며 전체 컨텍스트를 포착하지 못할 수 있음
- 전체 소스 읽기(full source read): 전체 파일 내용이 검사됨
- 구현에서 추론됨(inferred from implementation): 코드가 어떻게 동작하는지에서 추론되었으며 명시적으로 명시되지 않음
- 주석/테스트/픽스처에서 추론됨(inferred from comments/tests/fixtures): 권위 있는 컨텍스트가 아닌 곳에서 가져옴; 최대 강한 추론으로 취급
- 테스트에 의해 동작 확인됨(behavior verified by test): 통과한 테스트 실행에 의해 확인됨
- 알 수 없음(unknown): 근거가 확립되지 않음; 사실로 제시하지 마십시오
최종 보고서 및 지향 문서에서 각각의 사소하지 않은 주장에 위 출처 중 하나를 레이블로 지정하여 독자가 행동하기 전에 어떤 주장을 재확인해야 하는지 판단할 수 있도록 하십시오.
발견 순서
사용자 지정 참고: 아래의 발견 순서는 의도적으로 광범위하게 설정되어 편집 없이 대부분의 프로젝트 형태에서 작동합니다. 특정 프로젝트에 대해 파일 경로와 순서를 조정할 수 있지만, 이는 선택 사항입니다. 첫 사용 전에 필요하지 않습니다.
다음 순서로 실행하십시오:
CLAUDE.md,AGENTS.md,README.md와 같은 프로젝트 명령 파일(있는 경우) - 제품 목적, 에이전트 규칙, 프로젝트 규칙. 문서-가설 규칙- 이 문서들을 권위 있는 진실이 아닌 유용한 가설로 취급하십시오.
- 아키텍처, 라우트, 배포, 테스트 및 진실 공급원 파일에 대한 영향력이 큰 사실 주장을 추출하십시오.
- 의존하기 전에 소스 코드에 대해 해당 주장을 확인하십시오. 향후 편집에 영향을 미칠 주장에 집중하고 모든 문장을 감사하지 마십시오.
CODEBASE_MAP.md에 이러한 문서의 주장을 복사할 때는 소스/설정에서 독립적으로 확인됨 또는 기존 문서에서 상속됨 중 어느 것인지 레이블을 지정하지 않고 복사하지 마십시오.- 명령 문서가 소스가 보여주는 것과 비교하여 오래되었거나 오해의 소지가 있는 경우, 숨겨진 위험 보고 규칙에 따라
OPEN_QUESTIONS.md에 차이를 기록하고 문서 드리프트로 레이블을 지정하십시오. - 명령 레이어 토폴로지를 매핑하십시오: 어떤 명령 파일이 있는지(예:
CLAUDE.md,AGENTS.md,.claude/settings.json)와 어떤 범위(프로젝트-로컬 대 사용자-레벨)인지 기록하십시오. 이를CODEBASE_MAP.md에 기록하십시오. 이는 미래의 에이전트가 어떤 규칙이 적용되는지 아는 데 도움이 됩니다.
- 프로젝트 매니페스트(예:
package.json,pyproject.toml,Cargo.toml) - 종속성, 스크립트, 빌드/테스트 명령어 - 빌드 및 설정 파일(예: 프레임워크 설정, 번들러 설정) - 어댑터, 빌드 설정
scripts/디렉토리(있는 경우) - 패키지 스크립트나 CI에 표시되지 않는 수동 실행 도구를 포함할 수 있음- 진입점 및 라우팅 레이어 - 모든 페이지, 컨트롤러 또는 API 라우트
- 핵심 비즈니스 로직 - 도메인 유형, 모델, 점수, 보고 로직
- 서버 측 서비스 - 인증, DB/스키마, 이메일, 외부 통합
- UI/프레젠테이션 레이어 - 컴포넌트, 뷰, 템플릿
- 국제화 또는 복사 파일 - 로케일 파일
- 요청 수명 주기 / 미들웨어 - 훅, 인터셉터, 미들웨어
- 데이터베이스 레이어 - 마이그레이션, 스키마 스냅샷
- 테스트 - 테스트 구조 및 커버리지 형태
- 문서 - 기존 문서, 검증 매트릭스. 릴리스 계획, 마일스톤 추적 문서 또는 버전 변경 로그가 발견되면
CODEBASE_MAP.md에## Release status섹션을 추가하여 현재 버전, 활성 마일스톤 및 다음 릴리스를 차단하는 사항을 요약하십시오. 릴리스 수명 주기 아티팩트가 없으면 이 섹션을 생략하십시오. - 알려진 불확실성
프레임워크별 프로브
관련 프레임워크가 감지되면 일반 발견 순서에 추가하여 이러한 프로브를 적용하십시오.
재사용 가능한 스킬은 현재 SvelteKit에 대한 하나의 명시적인 조정 프로브 세트를 포함합니다. 다른 프레임워크는 향후 실전 또는 평가 증거가 전용 조정 프로브 섹션을 정당화하지 않는 한 일반 발견 순서를 사용합니다.
SvelteKit
SvelteKit 프로젝트가 감지되면 다음 파일 패턴을 글로브하십시오:
src/routes/**/+page.svelte: UI 라우트 페이지; 각 파일은 라우트 후보입니다. 최상위src/routes/+page.svelte뿐만 아니라 하위 디렉토리도 확인하십시오.src/routes/**/+page.server.ts: 서버 측 데이터 로딩, 폼 액션 및 라우트 수준 액세스 제어src/routes/**/+layout.svelte: 공유 레이아웃 셸src/routes/**/+layout.server.ts: 레이아웃 수준 인증, 세션 또는 데이터에 대한 서버 측 로드 함수src/routes/**/+server.ts: API 엔드포인트 및 서버 전용 요청 처리기
서버 측 라우트 파일(+page.server.ts, +layout.server.ts, +server.ts)은 인증, 데이터 로딩, 폼 액션, API 엔드포인트 및 라우트 수준 액세스 제어를 이해하는 데 중요합니다. 라우트 또는 변경 영역을 매핑할 때 건너뛰지 마십시오.
- 표준 앱 셸 템플릿은
src/app.html입니다. svelte.config.js의 어댑터 선택이 배포 대상을 결정합니다. 배포 관련 주장을 하기 전에 확인하십시오.
CI/배포 정밀도 규칙
CI 또는 배포 워크플로 파일을 읽을 때 운영상 관련된 세부 정보를 보존하십시오. 구체적인 내용을 모호한 요약으로 반올림하지 마십시오.
다음을 포착하여 보고하십시오:
- 동시성 그룹 이름(어떤 실행이 서로 경쟁하는지)
cancel-in-progress동작 -true인 경우 "최신 실행이 동일 그룹의 진행 중인 실행을 취소합니다"라고 말하고, 단순히 "병렬 배포를 방지합니다"라고 말하지 마십시오.fail-fast동작- 배포 아티팩트 경로
- 타임스탬프 또는 해시 구성 요소를 포함한 릴리스 명명 형식
- 이전 릴리스 또는 아티팩트에 대한 보존 및 정리 정책
- 수동 대 자동 트리거 조건
- 필요한 비밀 및 환경 변수
- 배포가 제자리에서 덮어쓰는지, 임시 경로에 준비하는지, 심볼릭 링크를 사용하는지, 또는 버전이 지정된 릴리스 디렉토리를 사용하는지 여부
워크플로 파일에서 직접 읽은 경우 CI/배포 주장에 소스/설정에서 독립적으로 확인됨 레이블을 지정하십시오. 운영자가 인시던트 중에 필요로 할 정밀도를 잃는 방식으로 이러한 세부 정보를 요약하지 마십시오.
읽기 깊이 휴리스틱
기본적으로 모든 대규모 CSS, 설정 또는 생성된 파일을 읽지 마십시오.
- 전체 읽기: 요청된 작업에 직접적인 영향을 미치는 파일(진입점, 라우팅, 인증, 스키마, 빌드 설정, 편집할 파일).
- 부분 읽기 또는 경로 확인 전용: 대규모 스타일 시트, 벤더 코드, 생성된 출력 또는 작업과 관련 없는 설정 파일과 같은 2차 표면. 파일의 경로만 확인하거나 일부만 읽는 경우 신뢰도 레이블 아래에 정의된 path existence confirmed 또는 부분 읽기 레이블을 사용하여 보고서에 명시적으로 말하십시오.
- 건너뛰기: 명백히 범위를 벗어난 파일(예: 바이너리 자산, 잠금 파일, 테스트 스냅샷). 특정 질문이 관련성을 만들지 않는 한 건너뛰십시오.
확신이 들지 않으면 먼저 존재를 확인하고 주장이 필요한 경우에만 전체를 읽는 것을 선호하십시오.
경로 존재 대 내용 읽기
경로 존재만으로는 저위험 인벤토리 주장(디렉토리 구조 확인, 파일 수 나열, 설정 파일이 존재함을 기록)에 충분합니다.
주장이 동작, 아키텍처, 위험, 명령어, 배포, 인증, 라우팅 또는 변경 영역에 영향을 미치는 경우 실제 파일 내용을 읽으십시오. 파일을 검사하는 것이 저렴하고 내용이 맵에 실질적으로 영향을 미칠 때 경로 존재만으로 주장에 소스/설정에서 독립적으로 확인됨 레이블을 지정하지 마십시오.
작은 진실 공급원 파일 읽기 규칙
작은 파일이 프로젝트 전체에서 사용되는 어휘 또는 진실 공급원 토큰을 정의하는 것으로 보이는 경우, 문서에서 어휘를 상속받지 말고 어휘를 확인하기에 충분히 파일을 읽으십시오.
이 규칙이 적용되는 예:
- CSS 사용자 정의 속성 토큰 파일
- 라우트 또는 메뉴 설정 파일
- 작은 스키마 또는 상수 파일
- 명령어 또는 플러그인 레지스트리
충분할 때 부분 읽기를 사용하십시오. 결과 주장에 적절한 주장 출처 레이블(부분 읽기, 전체 소스 읽기)을 지정하십시오. 실제로 파일을 읽지 않은 경우 소스/설정에서 독립적으로 확인됨 레이블을 지정하지 마십시오.
저렴한 아티팩트 글로브 규칙
정적 자산, 스크립트, 생성된 출력, 문서, 테스트, 마이그레이션 또는 설정 파일의 존재 또는 범위에 대한 열린 질문을 남기기 전에 저렴한 경로 글로브로 해결하십시오.
시도해 볼 일반적인 글로브 패턴:
static/**/*public/**/*scripts/**/*tests/**/*또는test/**/*또는spec/**/*.github/workflows/*docs/**/*migrations/**/*dist/**/*또는build/**/*
기본적으로 일치하는 모든 파일을 깊이 읽지 마십시오. 글로브를 사용하여 존재 및 범위 질문을 저렴하게 해결하십시오. 특정 파일의 내용이 필요한 경우에만 대상 읽기를 후속 조치하십시오.
열린 질문
질문이 발생할 때마다 추적하십시오. 확인되지 않은 가정에 따라 행동하지 마십시오.
기록 규칙:
- 숨겨진 위험 보고 규칙: 발견 중 또는 맵을 작성할 때 위험 신호, 알려지지 않은 영역 및 위험한 가정을 발견하면
OPEN_QUESTIONS.md에 추가하십시오. 예를 들어, "이 CI 파이프라인이 어떤 환경에 배포되는지 확인할 수 없습니다. 우리는 prod에 있다고 가정했지만 확인되지 않았습니다." 또한 부재 또는 문서 드리프트에 대한 메모: 예를 들어CLAUDE.md가 6개월 전에 업데이트되었거나 소스 코드와 모순되는 경우OPEN_QUESTIONS.md에 기록하십시오. - 부정적인 공간에 대한 주장 하지 않기: 발견되지 않은 것을 부재라고 가정하기 쉽습니다. 대신 포괄적인 글로브 또는 특정 조회를 사용하여 부재를 확인할 수 있는 경우(예: 디렉토리 글로브가 일치하는 파일을 반환하지 않음)에만 말하십시오. 예를 들어 패키지 스캐너가 사용됨을 나타내는 구성이 없는 경우 단순히 찾지 못했다고 말하는 대신 "설치된 정적 분석 사전 커밋 후크가 없음(glob이 일치하는 설정 없음)"이라고 말하십시오.
모든 질문에는 주장과 동일한 신뢰도 레이블이 부착되어야 합니다.
동기화 및 산출물 규칙
동기화
- 빠른 동기화(기본값): 가장 저렴한 유효성 검사를 실행하고 불일치가 발견된 경우에만 전체 동기화로 폴백합니다.
CODEBASE_MAP.md가 마지막ORIENTATION_STATE.json이후 변경 사항이 없음을 글로브할 수 있으면 즉시 동기화된 것으로 표시하십시오. - 전체 동기화: 모든 발견 단계를 처음부터 다시 실행하고, 완전히 새로운 산출물 패키지를 작성하고,
ORIENTATION_STATE.json을 업데이트하고, 이전 패키지가 작성된 이후 변경된 모든 사항을 나열하는 변경 요약을 출력하십시오. 빠른 동기화가 불일치를 감지하거나 사용자가 명시적으로 요청한 경우에만 이 작업을 수행하십시오.
산출물
Orient 산출물 패키지는 다음 파일로 구성됩니다. 관리할 때마다 존재와 올바른 형식을 확인하십시오:
docs/ai/CODEBASE_MAP.md- 마지막 동기화 시점의 저장소에 대한 구조적 지식.## Instruction file topology섹션과 발견 순서의 이전 단계에서 매핑된 모든 항목을 포함합니다.docs/ai/OPEN_QUESTIONS.md- 작업 전에 해결해야 하는 알려진 불확실성 목록.docs/ai/CHANGE_SURFACES.md- 주요 편집 지점(소스 파일, 설정 파일, 인프라 파일) 목록. 파일 경로는 소스 루트를 기준으로 합니다.## Route inventory및 유사한 구조적 인벤토리를 포함합니다. SvelteKit의 경우 라우트 인벤토리에는+page.svelte,+page.server.ts,+layout.server.ts,+server.ts파일이 포함되며 각 라우트와 액세스 제어 또는 데이터 요구 사항을 설명합니다.docs/ai/ORIENTATION_STATE.json-docs/ai/산출물의 현재 상태를 기록하는 머신 판독 가능 매니페스트. 최상위 키:schema_version,last_sync_commit,last_sync_timestamp,package_complete,scope,tree_condition.
ORIENTATION_STATE.json 스키마:
{
"schema_version": "1.0",
"last_sync_commit": "<current HEAD commit hash>",
"last_sync_timestamp": "<ISO 8601 timestamp of last sync>",
"package_complete": true,
"scope": "full",
"tree_condition": "clean"
}
scope 값: full(전체 저장소 동기화) 또는 특정 범위 문자열(예: src/routes). tree_condition 값: clean(커밋된 HEAD와 일치하는 작업 트리), dirty(커밋되지 않은 변경 사항 있음) 또는 unavailable(Git 기록을 사용할 수 없음).
ORIENTATION_STATE.json이 없으면 패키지가 동기화되지 않은 것으로 간주하고 주의해서 취급하십시오(레거시 채택 규칙 참조).
산출물 동기화의 최종 보고서는(마지막 동기화 이후) 변경된 사항이 없는 경우를 포함하여 항상 각 산출물 파일의 상태를 명시적으로 언급해야 합니다.
빠른 동기화 상세
빠른 동기화는 다음으로 구성됩니다:
ORIENTATION_STATE.json이 존재하고 구문 분석 가능한지 확인합니다. 그렇지 않은 경우 전체 동기화로 폴백합니다.last_sync_commit이 현재 HEAD와 일치하는지 확인합니다. 그렇지 않은 경우 전체 동기화로 폴백합니다.tree_condition이 유효한 값인지 확인합니다.dirty인 경우 더티 트리 규칙을 따릅니다.package_complete가true인지 확인합니다. 그렇지 않은 경우 전체 동기화로 폴백합니다.CODEBASE_MAP.md,OPEN_QUESTIONS.md,CHANGE_SURFACES.md파일 각각이 존재하는지 빠르게 확인합니다. 누락된 파일이 있으면 전체 동기화로 폴백합니다.- 모든 확인을 통과하면 패키지를 동기화된 것으로 선언하고 다시 동기화하지 않고 진행합니다.
빠른 동기화는 전체 내용을 읽지 않고 패키지 파일의 경로 존재와 메타데이터 신선도를 확인합니다.
제외 목록
다음 파일은 발견 및 동기화 중에 무시해야 합니다:
docs/ai/자체(산출물이 다른 산출물을 인덱싱하지 않도록 하기 위해)node_modules/,.git/,dist/,build/,target/,__pycache__/,.venv/,.env/와 같은 일반적인 생성 또는 종속성 디렉토리- 잠금 파일(
package-lock.json,yarn.lock,pnpm-lock.yaml,Gemfile.lock,poetry.lock) - 이진 자산(이미지, 글꼴, 압축 파일, 컴파일된 바이너리)
- 공급업체 또는 복사된 종속성 디렉토리(예:
vendor/,.godot/)
파일 제외로 인해 누락된 정보가 있는 경우 이를 알려진 인벤토리 구멍으로 OPEN_QUESTIONS.md에 기록하십시오.