Communitygithub.com

dubbl-a/house-rules

저장소의 벤더드 하우스 파일을 설치된 플러그인과 동기화하며, 로컬 편집 내용을 자동으로 폐기하지 않습니다.

house-rules란 무엇인가요?

이 스킬은 저장소에 벤더링된 하우스 규칙 파일을 설치된 플러그인 버전과 동기화하는 `/house-rules:sync` 명령을 구현합니다. 플러그인 루트의 `house` CLI 스크립트(`init`, `render`, `check` 하위 명령 포함)를 사용하여 로컬 편집 내용을 절대 자동으로 덮어쓰지 않으면서 관리되는 파일을 업데이트합니다. 이 스킬은 먼저 dry-run 계획을 생성하고, 각 관리 파일을 '깨끗함', '누락됨', '로컬 수정됨'으로 분류합니다. 로컬 수정된 파일의 경우 upstream-first PR 제출, 편차 기록 및 관리 해제, 또는 사용자 확인 후 강제 덮어쓰기라는 세 가지 명시적인 종료 옵션을 제공합니다. 동기화가 완료되면 스테이징, gitignore 확인, 버전 핀 확인, 벤더드 체커 실행, 의사 출력 보고 등 후속 단계를 수행하여 규칙이 제대로 적용되고 CI가 일관된 상태를 확인할 수 있도록 합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/dubbl-a/house-rules/tree/HEAD/plugins/house/skills/sync

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

하우스 동기화

저장소의 벤더드 하우스 파일을 설치된 플러그인과 최신 상태로 유지하며, 로컬 편집 내용을 절대 자동으로 폐기하지 않습니다. 이 스킬은 오직 /house-rules:sync를 통해서만 호출하세요. 파일을 쓰는 스킬이므로 규칙에 대한 일반적인 질문(예: "/house-rules:conventions" 사용)에서는 실행되지 않습니다.

이 스킬이 사용하는 CLI:

node ${CLAUDE_PLUGIN_ROOT}/scripts/house <init|render|check> [--repo <path>] [--apply] [--force-managed <path>]

--repo의 기본값은 현재 디렉터리입니다. init, render, check 이외의 하위 명령은 존재하지 않습니다.

기본 경로: 계획 후 적용

동기화에는 정확히 하나의 기본 경로가 있습니다. 매번 이 순서대로 실행하세요.

1. 저장소가 하우스를 채택했는지 확인

저장소 루트에서 house.json을 읽습니다. house.json이 없으면 이 저장소는 한 번도 부트스트랩되지 않은 것입니다: 중단하고 사용자에게 먼저 /house-rules:bootstrap을 실행하라고 알리세요. 매니페스트가 없다고 해서 "동기화할 것이 없다"고 처리하지 마십시오.

2. 계획 (dry-run)

node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <path>

--apply 없이 실행하면 계획만 수립합니다. .house/lock.json(각 항목: path, module, source, bodySha256)을 읽고 디스크에 있는 각 관리 파일의 현재 본문 해시를 잠금 파일 및 새로 렌더링된 본문과 비교합니다. 각 관리 파일을 정확히 하나의 버킷으로 분류합니다:

  • 깨끗함. 디스크의 해시가 잠금 파일과 일치합니다. 계획: 새로 렌더링된 본문으로 덮어씁니다.
  • 누락됨. 디스크에 파일이 없습니다. 계획: 복원합니다.
  • 로컬 수정됨. 디스크 해시가 잠금 파일 및 렌더링된 no-op과 모두 일치하지 않습니다. 계획: 거부합니다. 아래 세 가지 종료 옵션을 참조하세요.

다른 작업을 수행하기 전에 계획을 출력하세요. 깨끗하거나 누락된 파일이라도 이 단계에서는 아무것도 적용하지 마십시오.

3. 로컬 수정됨: 세 가지 종료 옵션, 절대 자동 선택 없음

로컬 수정된 관리 파일은 병합되지 않으며, 덮어쓰지 않으며, 조용히 방치되지 않습니다. 디스크의 파일과 하우스가 렌더링할 내용의 차이점을 출력한 다음, 정확히 다음 세 가지 종료 옵션을 이 순서대로 출력하고 해당 파일에 대해 중단합니다 (--apply에서도 파일은 그대로 유지되며 쓰기에서 제외됩니다):

  1. Upstream-first. 하우스 패키지 저장소 자체(dubbl-a/house-rules)에 변경 사항을 담은 PR을 열어, 편집 내용이 개인 포크가 아닌 모든 사람을 위한 새로운 하우스 규칙이 되도록 합니다. 이것이 권장되는 종료 옵션입니다.
  2. 편차 기록 및 관리 해제. house.json의 deviations 배열에 why와 함께 항목을 추가하고, 파일을 관리 세트에서 제거한 후 저장소의 CLAUDE.md ## 하우스와의 편차 섹션에 미러링합니다. 편집 내용이 진정으로 저장소 특정적이며 절대 upstream으로 올라가지 않을 때 사용합니다.
  3. 강제 덮어쓰기. 다음을 실행합니다:
    node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <path> --force-managed <path>
    
    로컬 편집 내용이 폐기 가능하다고 확인된 경우에만 사용하며, 가장 빠르기 때문에 기본값으로 사용하지 마십시오. 실행하기 전에 사용자에게 확인을 요청하세요. 사용자를 대신하여 요청 없이 선택하지 마십시오.

네 번째 옵션을 제공하지 말고, 이를 선택을 기다리며 루프를 도는 대화형 메뉴로 만들지 마십시오. 세 가지 종료 옵션을 실행 결과로 명시한 후, 사용자(또는 이 스킬의 이후 호출)가 그중 하나를 선택하여 실행하도록 하세요.

4. 적용

깨끗하고 누락된 파일이 처리되고 모든 로컬 수정 파일이 세 가지 종료 옵션 중 하나로 라우팅되거나 의도적으로 거부된 상태가 되면, 다음을 적용합니다:

node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <path> --apply

이 명령은 깨끗하고 누락된 파일을 씁니다. 여전히 거부된 로컬 수정 파일은 절대 쓰지 않습니다. --force-managed만이 그렇게 할 수 있으며, 지정된 하나의 경로에 대해서만 가능합니다.

render가 warning: ... is git-ignored 줄을 출력하면 중단하고 계속 진행하기 전에 무시 규칙을 수정하세요. git이 볼 수 없는 대상은 체커나 CI에 도달하지 못합니다. .claude/settings.local.json만 무시하고, .claude/나 .house/는 절대 무시하지 마십시오.

render 또는 체커가 warning: module is not in house.json, but <dir>/ exists here를 출력하면, 이는 이 저장소의 house.json이 작성된 후에 모듈이 제공되었으며, 저장소가 modules 아래에 "<name>": {"enabled": true}를 추가할 때까지 해당 규칙이 벤더링되지 않았다는 의미입니다. 키를 직접 추가하지 마십시오: 경고 줄을 그대로 동기화 PR 본문에 복사하고, 해당 줄 위에 새 모듈이 이 저장소에 적용되며 수용자의 선택이 필요하다는 내용의 줄을 추가하세요.

4b. render가 쓴 파일을 경로별로 스테이징

git add house.json .house/ .claude/rules/house/

렌더 계획에 scripts/house/의 파일이 나열된 경우에만 해당 명령에 scripts/house/를 추가하세요. pathspec이 일치하는 항목이 없으면 git은 전체 명령을 거부합니다. git add -A가 아닌 명시적 경로로 추가하세요. 체커와 CI는 git ls-files를 읽으므로 스테이징되지 않은 렌더링된 파일은 아무도 확인하지 않으며, 블랭킷 추가는 트리에 있는 다른 모든 것을 쓸어담을 수 있습니다.

Render의 Scaffolded 목록(.github/PULL_REQUEST_TEMPLATE.md, .github/workflows/pr-checks.yml, CLAUDE.md 스켈레톤)은 관리 파일이 아니므로 [untracked] 경고가 이를 볼 수 없습니다: 해당 파일들을 검토한 후 경로별로 스테이징하세요.

스캐폴드는 저장소당 한 번씩만 제공되며, 렌더링당 한 번이 아닙니다. 잠금 파일의 scaffolds 목록은 이 저장소에 이미 제공된 템플릿을 기록합니다. 기록된 템플릿은 해당 파일이 여전히 디스크에 있든 없든 다시 작성되지 않습니다. 따라서 CLAUDE.md에 병합되고 삭제된 CLAUDE.md.house-skeleton은 삭제된 상태로 유지되며, 다시 동기화할 때 rm할 필요가 없습니다. 저장소가 다시 필요로 하는 경우 render --apply --scaffold는 누락된 스캐폴드를 작성하며, 이미 있는 파일을 덮어쓰지 않습니다. scaffolds 키는 0.2.3 이상에서 첫 번째 동기화 시 잠금 파일 diff에 나타날 것으로 예상됩니다. 이는 해시가 아닌 기록이며, 아무것도 거부하지 않습니다.

4c. Gitignore 도구 임시 파일

저장소의 .gitignore에 .claude/worktrees/와 .superpowers/가 포함되어 있는지 확인하고, 누락된 줄을 추가하세요. git status에 나타나는 도구 임시 파일은 git add -A 한 번으로 커밋될 수 있습니다.

5. 핀 확인

house.json에 로드된 플러그인 버전이 포함되어 있는지 확인하세요. render가 이 버전을 작성하며, 직접 편집하지 마십시오. render --apply는 version 필드를 다음 위치의 플러그인 버전으로 설정합니다:

${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json

이를 확인하기 위해 installed_plugins.json을 읽지 마십시오. 이는 저장소 간 설치 상태를 기록하며 현재 로드된 것과 지연되거나 다를 수 있습니다. CLAUDE_PLUGIN_ROOT 아래의 plugin.json이 실제로 이 동기화를 실행 중인 버전입니다.

6. 벤더드 체커로 확인

CI와 prebuild가 실제로 실행할 방식으로 체커를 실행하세요. 플러그인 자체 복사본이 아닙니다:

node .house/check.mjs

node ${CLAUDE_PLUGIN_ROOT}/scripts/house check --repo <path>는 플러그인 자체 페이로드에 대해 동일한 로직을 실행하며, .house/check.mjs가 저장소에 벤더링되기 전(첫 번째 동기화)에 유용합니다. 벤더드 복사본이 있으면 이를 직접 실행하여 파일이 전달되는 파일임을 증명하고, 동일해 보이는 복사본이 아님을 확인합니다.

여기서 [untracked] 경고는 해당 파일에 대해 4b 단계를 건너뛰었음을 의미합니다. 스테이징하고 다시 실행하세요. [gitignored] 발견은 4단계의 무시 규칙이 여전히 관리 파일을 숨기고 있음을 의미합니다.

7. 의사 출력 보고

체커가 실행된 후 의사를 실행하고 그 줄을 보고합니다:

node ${CLAUDE_PLUGIN_ROOT}/scripts/house doctor --repo <path>

각 출력 줄의 의미 (doctor가 출력하는 레이블 기준):

  • effective branch guard: plugin | repo | NONE.
    • NONE: house.json이 없고 저장소-로컬 훅도 없습니다. 현재 보호된 브랜치에 대한 직접 커밋을 보호하는 것이 없습니다.
    • repo: 저장소-로컬 .claude/hooks/no-direct-master.sh 파일이 있거나, .claude/settings.json에 hooks 블록이 있습니다. 마이그레이션 중에는 저장소 훅이 우선합니다. 플러그인 훅은 지연되고 0으로 종료됩니다.
    • plugin: house.json이 있고 저장소-로컬 훅 신호가 모두 없습니다. 플러그인 훅이 실제로 branchPolicy와 protectedBranches를 적용합니다. house.json이 guard 레코드를 가지면 plugin (recorded <date>)로 출력하고, 그렇지 않으면 plugin (unrecorded)로 출력합니다. 이는 체커의 guard 경고가 해결되었는지 여부에 관한 것일 뿐입니다. 훅은 어느 쪽이든 동일하게 적용합니다.
  • git-hook floor: .... 벤더드 .githooks/ 트리가 실제로 이 클론의 git에 연결되어 있는지 여부입니다. core.hooksPath는 .git/config에 있으므로 기계 상태이며, 어떤 클론, 렌더링 또는 PR도 전달하지 않습니다. 체커는 이를 읽지 않으며(ADR 0008은 체커를 저장소 전용으로 유지함), doctor가 이를 보고하는 곳입니다.
    • armed (core.hooksPath=<path>, <scope>): git이 여기서 floor를 실행합니다. 할 일이 없습니다.
    • NOT armed -- core.hooksPath is unset in this clone: floor가 렌더링되었지만 비활성 상태입니다. house render --apply가 이를 활성화하고, 플러그인이 설치된 저장소에서 세션을 시작할 때도 활성화됩니다.
    • NOT armed -- core.hooksPath is <other>: 다른 도구(hussy, lefthook, 모노레포 규칙)가 이 저장소의 유일한 hooksPath를 소유하고 있습니다. House는 절대 덮어쓰지 않습니다. 거기서 floor를 연결하거나 설정을 해제하고 render를 다시 실행하세요.
    • not rendered here (missing: <paths>): 7개의 floor 파일 중 하나 이상이 없으며, 줄이 어떤 파일인지 지정합니다. 7개 모두 누락은 단순히 floor를 아직 렌더링하지 않은 저장소입니다. 하나만 누락된 것은 보기보다 심각합니다. 모든 가드는 .githooks/house-lib.sh를 소싱하고 해당 소스가 실패하면 0이 아닌 종료 코드로 종료되므로, 라이브러리만 누락된 floor는 모든 커밋을 닫힌 실패 대신 열린 실패로 만듭니다. 어느 쪽이든 render를 실행하세요.
    • not applicable: 이 루트에 house.json이 없거나 branchPolicy가 pr이 아닙니다.
    • 들여쓰기된 후속 줄은 floor를 보호적이지 않게 만드는 요소를 보고합니다. foreign hooks in this clone's .git/hooks: 활성화가 거부됩니다. core.hooksPath는 .git/hooks를 완전히 대체하여 자동으로 비활성화하기 때문입니다. not executable: git은 비트가 없는 훅을 자동으로 무시하므로, 모드 손실은 열린 실패입니다. render가 이를 복원합니다(파일을 이미 읽을 수 있는 클래스에 대해서만 비트를 추가하므로, 의도적으로 0600인 훅은 0700으로 돌아오며 확대되지 않습니다). reference-transaction: supported by git <version> (>= 2.28) 또는 inert on git <version> (needs 2.28): 2.28 이상에서 floor에는 어떤 플래그도 끌 수 없는 멤버가 있으며, inert 라인은 미용상의 문제가 아닌 실제 격차입니다. 2.28 미만에서는 --no-verify가 pre-commit과 pre-push를 함께 건너뛰며, 이를 잡을 다른 것이 없으므로, 해당 git에서는 플래그가 세션 중 PreToolUse 훅에 의해서만 거부되며, 이 훅은 세션이 루프에 없을 때는 존재하지 않습니다. 이 라인을 git 업그레이드 프롬프트로 취급하고, 메모로 취급하지 마십시오.
  • jq on PATH: yes | no. 훅이 없어도 거부하지만(수동으로 작성된 거부 JSON), 격차를 보고하여 수정되도록 합니다.
  • pin vX matches plugin vY | pin vX differs from installed plugin vY. house.json의 version과 플러그인 자체의 plugin.json을 비교한 것으로, 5단계와 동일한 비교입니다. differs는 핀 범프가 아직 적용되지 않았거나 건너뛰어졌음을 의미합니다.
  • npm wiring (.house/check.mjs referenced by): <scripts> | none found. .house/check.mjs --only=drift,todo를 호출하는 check:docs(또는 이에 상응하는 경량) 스크립트와 전체 .house/check.mjs를 호출하는 check:house 스크립트가 있을 것으로 예상합니다. 둘 중 하나라도 누락되면 package.json을 직접 편집하는 대신 복사하여 붙여넣을 수 있는 스니펫을 출력합니다:
    "check:docs": "node .house/check.mjs --only=drift,todo"
    "check:house": "node .house/check.mjs"
    
  • rule-load positive control: .... InstructionsLoaded 훅이 연결되어 있는지, 그리고 그 자체 로그가 실제로 무엇을 목격했는지 여부입니다. 이것이 없으면, glob이 일치하지 않는 규칙은 아무것도 하지 않는 규칙과 정확히 동일하게 보입니다. repo (.claude/settings.json): 저장소가 자체 훅을 선언합니다. plugin hook; log <path>: last load <ts>, <n> of <m> vendored rules seen: 플러그인 자체 훅이 연결되어 있고 하나 이상의 로드를 기록했으며, 실제로 로드된 벤더드 규칙 파일의 실제 수를 보여줍니다. <n>이 <m보다 작으면 줄은 ; not seen in this log: <names>로 계속되며, 로그에 로드가 없는 각 벤더드 규칙의 이름을 지정합니다. 개수만으로는 무언가 잘못되었음을 알 수 있지만 어떤 파일을 열어야 하는지는 알 수 없기 때문입니다. 그 목록을 평결이 아닌 단서로 읽으십시오. 로그는 자체적으로 트리밍되므로, 규칙이 아주 오래 전에만 로드된 후에도 나타날 수 있으며, 정직한 다음 단계는 규칙의 paths:가 주장하는 파일을 열고 doctor를 다시 실행하는 것입니다. 그럼에도 살아남는 이름은 해당 규칙의 범위가 작성된 파일에 도달하지 못하고 있음을 의미합니다. plugin hook declared; no log yet for this checkout: 플러그인 훅이 연결되었지만 여기서 아직 아무것도 기록하지 않았습니다. 이 저장소에서 세션을 시작하고 doctor를 다시 실행하세요. none wired: 아무것도 훅을 선언하지 않습니다.
  • git-ignored house destinations: none | <paths>. none이 아닌 것은 체커가 볼 수 없는 대상입니다. 4단계와 같이 무시 규칙을 수정하세요.

8. 저장소가 upstream에서 수정할 수 없는 항목을 항목당 하나의 이슈로 라우팅

동기화 또는 규정 준수 패스는 종종 패키지만이 처리할 수 있는 결과 및 경고를 표면화합니다: 체커 결함, 여기에 존재하지 않는 파일을 명명하는 규칙 앵커, 저장소에 필요하지만 스키마에 없는 구성 슬롯 등. 각 항목에 대해 동일한 세션에서 upstream에서 수정하거나(패키지 저장소에 대한 브랜치 및 PR, 3단계와 동일한 upstream-first 종료), 패키지 저장소에 실행 가능한 항목당 하나의 이슈를 제출하세요. 하나의 변경으로 종료할 수 있을 만큼 작아야 합니다.

여러 항목을 여러 항목 다이제스트 이슈로 일괄 처리하지 마십시오. 다이제스트는 가장 느린 항목이 도착할 때까지 종료할 수 없으며, 해당 항목을 독립적으로 우선순위를 지정할 수 없으며, 절반만 해결된 다이제스트가 누적됩니다. 이 저장소에 남는 것은 이 저장소가 수정할 수 있는 것뿐입니다.

탈출구

다음은 위의 기본 경로에서 인라인으로 표시되는 예외이며, 미리 선택할 수 있는 별도의 메뉴가 아닙니다:

  • house.json 없음: 1단계에서 중단하고 /house-rules:bootstrap을 가리킵니다.
  • 로컬 수정 파일: 3단계의 세 가지 종료 옵션.
  • 폐기 가능이 확인된 로컬 편집: --force-managed <path>, 사용자에게 확인을 요청한 후에만.
  • 저장소의 첫 번째 동기화, .house/check.mjs가 아직 벤더링되지 않음: 6단계에서 벤더드 경로 대신 house check --repo <path>를 사용하고, 이는 일회성 대체이며 정상 상태가 아님을 명시하세요.

하지 말아야 할 것

  • 로컬 수정 파일을 병합하지 마십시오. 절대 무음으로 덮어쓰지 마십시오.
  • 사용자의 다른 명시적 선택 없이 --force-managed를 실행하지 마십시오.
  • 잠금 파일, house.json의 버전 또는 git 무시 규칙을 수동으로 편집하지 마십시오.
  • 스캐폴드가 이미 기록된 경우에도 다시 쓰지 마십시오.
  • 보호된 브랜치에 직접 푸시하지 마십시오. 항상 PR을 사용하십시오.
  • git add -A를 사용하지 마십시오. 항상 명시적 경로를 사용하십시오.
  • 스테이징되지 않은 파일에 대해 체커를 다시 실행하지 마십시오. 먼저 스테이징하십시오.

동기화 후 PR 만들기

동기화가 완료되면(모든 단계가 성공적으로 완료됨) 동기화된 변경 사항이 포함된 PR을 만듭니다:

  1. 동기화를 위해 새 브랜치를 만듭니다: git checkout -b house/sync-$(date +%Y%m%d)
  2. 모든 변경 사항이 스테이징되었는지 확인합니다.
  3. git commit 실행 - House sync가 기본 커밋 메시지를 생성합니다.
  4. git push origin HEAD로 푸시하고 URL을 출력합니다.
  5. 템플릿(.github/PULL_REQUEST_TEMPLATE.md이 있는 경우 사용)을 사용하여 PR을 엽니다.
  6. PR 본문에 doctor 출력을 포함시킵니다.
  7. PR 설명에 오류, 경고 및 특히 거부된 로컬 수정 상태를 나열합니다.

render가 출력에 표시되는 package.json 변경을 생성하지 않은 경우 다음을 추가하세요:

### 추가 작업 없음
이 동기화는 `package.json` 스크립트를 변경하지 않았습니다.

render가 npm 스크립트를 추가한 경우 PR에 다음을 포함하세요:

### 새로운 npm 스크립트
이 동기화는 CI 통합을 위한 npm 스크립트를 추가했습니다. adopter는 이를 워크플로에 추가해야 할 수 있습니다.

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

관련 스킬