Codebase Trellis
AI 기반 코드 변경을 구조화, 지원 및 안전하게 통합합니다.
에코시스템:
codebase-orient는 코드베이스를 이해합니다.codebase-visualize는 코드베이스를 매핑합니다.codebase-trellis는 안전한 변경 성장과 통합을 지원합니다.
이 스킬을 사용해야 하는 경우
이 스킬을 사용해야 하는 경우
- 파일이 변경되었고 안전한 스테이징, 커밋 계획 또는 커밋 실행이 필요한 경우
- 브랜치 또는 워크트리를 설정, 완료 또는 정리해야 하는 경우
- 푸시, PR 또는 CI 상태를 검사하거나 준비해야 하는 경우
- Git/GitHub 저장소 상태를 감사해야 하는 경우
- 장기 실행 에이전트 세션이 계속 진행되기 전에 구조화된 상태 검토가 필요한 경우
- 작업 트리가 더럽고 다음 적절한 단계가 명확하지 않은 경우
이 스킬을 건너뛰어야 하는 경우
- 작업이 Git 상태 불확실성이 없는 작고 단일 파일의 알려진 수정인 경우
- 읽기 전용 탐색이 진행 중이고 커밋/푸시/정리 작업이 계획되지 않은 경우
- 다른 스킬(
codebase-orient,codebase-visualize)이 방금 호출되었고 Git 작업이 뒤따르지 않는 경우
단순 vs 구조적 분류
워크플로를 실행하기 전에 각 호출을 분류합니다.
단순 패스:
- 국소적인 버그 수정
- 문서 전용 또는 복사 전용 변경
- 종속성 업데이트
- 소규모 리팩터링
- 테스트 전용 변경
- 이미 범위가 지정된 커밋 준비
구조적 패스:
- 광범위한 다중 파일 변경
- 여러 패키지
- UI + API + 테스트
- 마이그레이션 또는 생성된 파일
- 장기 실행 에이전트 작업
- 여러 커밋 예상
- 재개 또는 인계 가능성이 높은 경우
확실하지 않은 경우 기본값은 단순입니다. 검사 결과 작업이 처음보다 더 큰 것으로 판명되면 구조적으로 승격합니다. 안전 상태가 설정된 후에는 구조적에서 절대 강등하지 마십시오.
적용 계층
Trellis는 4계층 안전 모델 내에서 작동합니다. 이 계층들은 동등하지 않으며 어떤 계층도 다른 계층을 대체할 수 없습니다.
계층 1: 스킬 규율 (핵심 v1 계층)
스킬은 위험한 작업을 검사, 보고 및 차단합니다. 추가 훅이나 GitHub 액세스 없이 일반 Git 저장소에서 작동합니다. 이는 행동 기반입니다. 즉, 에이전트가 스킬을 따르는지에 따라 달라집니다.
계층 2: 로컬 Git 훅
저장소 로컬 훅은 커밋 또는 푸시 중에 실행될 수 있습니다. Trellis는 훅을 권장할 수 있지만 v1에서는 필요하거나 설치하지 않습니다. 훅이 누락되거나 --no-verify로 우회되거나 클론 간에 공유되지 않을 수 있습니다.
계층 3: Claude Code 훅
호스트 수준 훅은 도구 사용, 파일 변경 및 권한 주변에서 작동할 수 있습니다. 선택적 강화만 해당 – 독립형 핵심에는 필요하지 않습니다. 설치되어 있다고 가정하지 마십시오.
계층 4: GitHub 보호
GitHub 측 시행: 브랜치 보호, 규칙 세트, 필수 검사, 필수 리뷰, 서명된 커밋, 강제 푸시 제한, 병합 대기열, 비밀 검사, 코드 검사, Dependabot. API 액세스가 허용될 때 검사하고 보고합니다. 보호가 존재한다고 가정하지 마십시오.
비동등성 규칙:
- 스킬 규율은 훅이 아닙니다.
- 로컬 훅은 GitHub 브랜치 보호가 아닙니다.
- 통과하는 로컬 grep은 비밀 검사가 아닙니다.
- PR 헤드 검사는 병합 대기열 검사가 아닙니다.
- 보이는 녹색 체크는 관련 SHA에 대해 모든 필수 검사가 통과했음을 증명하지 않습니다.
계층을 사용할 수 없거나 확인할 수 없으면 명확하게 말하십시오.
상호 운용성 경계
독립형 핵심
Codebase Trellis는 자매 스킬 아티팩트를 요구하지 않고 일반 Git 저장소에서 작동해야 합니다. 소유:
- Git 상태 및 더티 상태 검사
- 스테이징, 언스테이징, 추적되지 않음, 무시됨, 생성됨, 민감함 및 사전 존재 변경 감지
- 커밋 그룹화 및 커밋 계획 전달
- 브랜치/워크트리 안전
- 푸시/PR/CI 게이트
- 정리 규칙
- Trellis 보고서 출력
선택적 조언 읽기
자매 스킬 아티팩트가 존재하는 경우 Trellis는 이를 조언 컨텍스트로만 읽을 수 있습니다.
codebase-orient(예: docs/ai/CODEBASE_MAP.md, docs/ai/CHANGE_SURFACES.md, docs/ai/OPEN_QUESTIONS.md):
- 저장소 레이아웃 및 패키지/워크스페이스 구조
- 알려진 검사 및 생성된 문서 정책
- 중요한 규칙 및 위험 영역
codebase-visualize(예: docs/ai/visualize/codebase-graph.json):
- 폭발 반경 및 영향을 받는 모듈
- 문서-코드 간선 및 높은 중심성 파일
규칙:
- 이러한 파일을 요구하지 마십시오.
- 다시 생성하지 마십시오.
- 자동으로 수정하지 마십시오.
- 시각화가 없어도 일상적인 커밋 계획을 차단하지 마십시오.
- 소스/구성/표준 문서보다 더 권위 있는 것으로 취급하지 마십시오.
인계 트리거
- 저장소 구조가 불분명하거나, 알려진 검사를 모르거나, 에이전트가 위험을 분류할 충분한 컨텍스트가 없는 경우
/codebase-orient를 제안합니다. - 변경 영향이 광범위하거나 아키텍처와 관련되거나, 종속성 관계가 중요하거나, 폭발 반경이 결정을 개선할 수 있는 경우
/codebase-visualize를 제안합니다.
보편적 규칙
항상:
- 저장소 루트, 브랜치 및 더티 상태를 식별하는 것으로 시작합니다.
- 명령을 제안하기 전에 상태를 표시합니다.
- 스테이징, 언스테이징, 추적되지 않음, 삭제됨 및 무시된 파일을 분리합니다.
- 부분적으로 스테이징된 파일을 모호하고 위험한 것으로 취급합니다.
- 모든 커밋 계획에서 민감한 파일을 제외합니다.
- 광범위한 경로 명령보다 정확한 파일 목록을 선호합니다.
- 명령 실패 시 중지합니다.
gh를 사용할 수 없거나 권한이 없는 경우 말합니다.- 보고서를 짧고 실행 가능하게 유지합니다.
- 알려진 것과 알려지지 않은 것을 보고합니다. 알려지지 않은 것을 가정된 안전으로 축소하지 마십시오.
절대:
- 정확한 파일 목록에 대한 명시적 승인 없이
git add .를 실행하지 마십시오. - 계획된 파일과 커밋 메시지를 보여주지 않고 커밋하지 마십시오.
- 커밋의 일부로 푸시하지 마십시오.
- 푸시의 일부로 병합하지 마십시오.
git push --force를 사용하지 마십시오.--force-with-lease를 추론하지 마십시오. 명시적으로 요청해야 합니다.- 브랜치 이름을 입력으로 확인하지 않고 브랜치를 삭제하지 마십시오.
- 이 세션에서 생성되지 않았거나 프로젝트 로컬 폐기 가능 워크트리가 아닌 워크트리를 제거하지 마십시오.
.env, 키, 토큰, 자격 증명 또는 무시된 파일을 커밋 계획에 포함하지 마십시오.- 확인하지 않고 테스트, CI 또는 GitHub 설정이 통과했다고 주장하지 마십시오.
- 로컬 grep 또는 보이는 검사만으로 "비밀 없음" 또는 "취약점 없음"을 주장하지 마십시오.
- 관련 SHA와 필수 검사를 모두 알지 못하면 CI가 녹색이라고 보고하지 마십시오.
- 사전 존재하는 더티 파일을 자동으로 포함하지 마십시오.
- 추적되지 않은 파일을 자동으로 포함하지 마십시오.
위험 게이트
읽기 전용 – 승인 불필요:
git status,git diff --stat,git log,git remote -vgh pr view,gh run list,gh repo view- 상태를 변경하지 않는 모든 검사 또는 진단 명령
낮은 상태 변경 – 실행 모드에서 가시적 계획 및 승인 필요:
- 로컬 브랜치 생성
- 로컬 워크트리 생성
- 명시적으로 나열된 파일 스테이징
- 승인된 계획에서 커밋 생성
높은 상태 변경 – 명시적 승인 필요:
- 푸시 (모든 브랜치)
- PR 생성
- 브랜치 병합
- 브랜치 리베이스
- 브랜치 보호 또는 규칙 세트 편집
- 브랜치 삭제
- 워크트리 제거
위험 – 입력 확인 및 명령 실행보다 출력 선호:
- 보호된 브랜치로 푸시 (브랜치 이름 입력 필요)
--force-with-lease푸시 (명시적으로 요청해야 함)git reset --hardgit clean -fd또는 추적되지 않은 파일 제거- 병합되지 않은 커밋이 있는 브랜치 삭제
- 공개 기록 다시 쓰기
- 비밀 기록 수정
git push --force는 항상 금지됩니다.
민감한 파일 패턴
이러한 파일을 커밋 계획에 절대 포함하지 마십시오. 사용자가 경고 후 재정의하면 다시 경고하고 권장하지 않습니다.
.env
.env.*
*.pem
*.key
*.p12
*.pfx
id_rsa*
*.cert
.aws/credentials
credentials.json
*.secret
token.txt
.npmrc
auth.json
service-account*.json
또한 제외: 무시된 파일, 빌드 출력, 캐시 및 종속성 폴더(저장소가 의도적으로 추적하지 않는 한).
일반적인 제외 사항:
node_modules/
dist/
build/
.cache/
.svelte-kit/
.next/
coverage/
__pycache__/
*.pyc
보안 가시성 경계
Trellis는 보이는 보안 신호를 보고할 수 있습니다. Trellis는 완전한 보안 스캐너가 아닙니다.
다음이 보이면 보고:
- 로컬 diff의 비밀 모양 파일 (
.env,*.key등과 일치하는 파일 이름 또는 패턴) - GitHub 비밀 검사 및 푸시 보호가 활성화된 것으로 보이는지 여부
- CodeQL 또는 코드 검사가 구성되었는지 여부
- Dependabot 경고 또는 보안 업데이트가 보이는지 여부
- 이 diff에서 종속성 파일이 변경되었는지 여부
절대 주장하지 마십시오:
- 로컬 grep이 아무것도 찾지 못했다는 이유만으로 "비밀 없음"
- 보이는 GitHub 검사가 녹색이라는 이유만으로 "취약점 없음"
- 전용 보안 도구를 통해 확인되지 않은 보안 상태는 깨끗함
GitHub/CI 가시성 경계
확인할 수 있는 것과 확인할 수 없는 것을 보고하십시오. 알려지지 않은 보호 상태를 가정된 안전으로 축소하지 마십시오.
CI 모드는 서로 다른 질문입니다. 혼동하지 마십시오:
PR 수준 준비 상태:
- 이 PR이 병합 준비가 되었습니까?
- 이 SHA에 대해 필수 검사가 통과했습니까?
- 보류, 건너뛰기 또는 취소된 검사가 관련이 있습니까?
워크플로 실행 검사:
- 이 실행이 실패한 이유는 무엇입니까?
- 어떤 작업 또는 단계가 실패했습니까?
- 로그 또는 아티팩트를 사용할 수 있습니까?
GitHub 보호 상태 – 다음 중 하나를 보고:
보호 상태: 확인됨 -- <발견된 내용 요약>보호 상태: 확인되지 않음. main이 보호된다고 가정하지 마십시오.
병합 대기열 – 병합 대기열이 필요한 경우 PR 헤드 검사는 최종 신호가 아닙니다. 별도로 보고:
- PR 헤드 검사
- 필수 검사
- 병합 대기열 또는 병합 그룹 검사(있는 경우)
- 확인된 SHA가 논의 중인 커밋과 일치하는지 여부
명시적인 사용자 승인 없이 병합 대기열에 추가하거나, 자동 병합을 활성화하거나, 병합하지 마십시오.
Trellis 보고서
Trellis 보고서는 모든 검사 또는 계획 패스의 핵심 출력입니다.
전체 형식
Trellis 보고서
루트 검사
- 저장소 루트: <현재 작업 디렉토리; 연결된 워크트리인 경우 워크트리 경로>
- 메인 저장소: <GIT_COMMON에서 파생된 상위 저장소 루트; 연결된 워크트리가 아닌 경우 생략>
- 브랜치:
- 원격/업스트림:
- 워크트리 상태: <연결된 워크트리(<경로>) / 메인 저장소 체크아웃 / 분리된 HEAD>
- ID/서명 상태:
- 기준 더티 파일(사전 존재):
얽힘 검사
- 스테이징된 변경:
- 언스테이징된 변경:
- 추적되지 않은 파일:
- 주목할 만한 무시/생성된 파일:
- 민감해 보이는 파일:
- 부분적으로 스테이징된 파일:
- 혼합 관심사:
성장 계획
- 제안된 변경 그룹:
- 제안된 커밋 경계:
- 제안된 PR 모양:
- 범위에서 제외된 파일:
- 사용자 결정이 필요한 파일:
게이트 검사
- 검사/읽기 안전: 예
- 스테이징 전 승인 필요:
- 커밋 전 승인 필요:
- 푸시 전 승인 필요:
- 병합/자동 병합 전 승인 필요:
- 정리/삭제 전 승인 필요:
캐노피 검사
- GitHub 저장소/PR 가시성:
- 필수 검사:
- CI 상태 및 확인된 SHA:
- 브랜치 보호/규칙 세트 상태:
- 병합 대기열 상태:
- 보이는 보안 신호:
- 알려지지 않음/확인되지 않은 보호:
다음 안전 조치
- 권장 사항:
- 정확한 명령(읽기 전용만 해당 또는 게이트 주석 포함):
- 사용자로부터 필요한 결정:
짧은 형식
단순 패스 또는 작은 작업 트리에 사용합니다.
Trellis 보고서
- 루트: <저장소 / 브랜치 / 워크트리 요약>
- 얽힘: <스테이징 / 언스테이징 / 추적되지 않음 / 민감 / 혼합 관심사 요약>
- 성장: <커밋/PR 그룹화 권장 사항>
- 게이트: <승인이 필요한 작업>
- 캐노피: <GitHub/CI/보호 상태(알려진 경우) 또는 "확인되지 않음">
- 다음: <하나의 안전한 다음 조치>
중지 형식
Trellis가 계속할 수 없거나 계속해서는 안 되는 경우 사용합니다.
Trellis 중지
- 중지 사유:
- 증거:
- 무시할 경우 위험:
- 안전한 복구 옵션:
- 권장 옵션:
중지 사유는 다음과 같습니다:
- 민감해 보이는 파일이 스테이징될 예정입니다.
- 사전 존재하는 더티 파일이 자동으로 포함될 예정입니다.
- 부분적으로 스테이징된 파일로 인해 의도가 모호합니다.
- 대상 브랜치가 보호되거나 알 수 없으며 푸시/병합이 요청되었습니다.
- 강제와 같은 작업이 명시적인 위험 수락 없이 요청되었습니다.
- 주장된 푸시 또는 CI 상태가 다른 SHA를 참조합니다.
- 다른 브랜치, 워크트리 또는 PR이 동일한 작업을 소유하고 있는 것으로 보입니다.
모드 라우팅
$ARGUMENTS를 읽습니다.
모드가 제공되지 않으면 audit을 실행합니다.
지원되는 모드:
audit: 읽기 전용 로컬 Git 및 GitHub 상태 검토start: 브랜치 또는 워크트리를 사용하여 격리된 작업 준비commit: 응집력 있는 커밋 계획 또는 실행push: 푸시 및 CI 모니터링 준비 또는 실행finish: PR을 통한 브랜치 완료, 로컬 병합, 유지 또는 폐기recover: Git 실수로부터 복구
audit 모드
읽기 전용 진단을 실행합니다. Trellis 보고서를 생성합니다. 로컬 또는 원격 상태를 절대 수정하지 마십시오.
Audit 사전 점검 – 로컬 Git
gh 가용성에 관계없이 항상 먼저 실행:
git rev-parse --show-toplevel 2>/dev/null || echo "ERROR: git repo가 아닙니다"
git branch --show-current
git status --short
git diff --stat
git diff --cached --stat
git log --oneline -10
git remote -v
git config --show-origin --show-scope --get user.name 2>/dev/null || echo "설정되지 않음"
git config --show-origin --show-scope --get user.email 2>/dev/null || echo "설정되지 않음"
git config commit.gpgsign 2>/dev/null || echo "설정되지 않음"
Audit 사전 점검 – 커뮤니티 파일 검사
각 파일의 로컬 존재/부재를 확인합니다. 존재/부재는 확인된 사실입니다. 콘텐츠 품질은 해당되지 않습니다:
test -f README.md && echo "존재" || echo "부재"
test -f LICENSE && echo "존재" || echo "부재"
test -f SECURITY.md && echo "존재" || echo "부재"
test -f CODE_OF_CONDUCT.md && echo "존재" || echo "부재"
test -f CONTRIBUTING.md || test -f .github/CONTRIBUTING.md && echo "존재" || echo "부재"
test -f .github/PULL_REQUEST_TEMPLATE.md && echo "존재" || echo "부재"
test -d .github/ISSUE_TEMPLATE && echo "존재" || echo "부재"
test -f CODEOWNERS || test -f .github/CODEOWNERS || test -f docs/CODEOWNERS && echo "존재" || echo "부재"
test -f .github/dependabot.yml || test -f .github/dependabot.yaml && echo "존재" || echo "부재"
test -d .github/workflows && echo "존재" || echo "부재"
GitHub 상태 – 가용성 게이트
gh 명령을 실행하기 전에:
- GitHub 원격이 있는지 확인:
git remote -v | grep github.com gh를 사용할 수 있는지 확인:gh auth status 2>/dev/null
GitHub 원격이 감지되지 않으면: 모든 GitHub 상태 필드를 unavailable -- non-GitHub remote로 보고합니다.
gh를 사용할 수 없는 경우...