기존 프로젝트 통합 가이드

| 항목 | 신규 프로젝트 | 기존 팀 프로젝트 | |------|------------|----------------| | `CLAUDE.md` | 새로 생성 | `Last sync:` 마커 없으면 건너뜀 | | `.claude/hooks/*.sh`

이미 운영 중인 팀 프로젝트에 ai-rules를 적용하는 방법.
신규 프로젝트는 profiles/_default.yaml을 복사해 바로 사용하면 됩니다.

---

신규 vs 기존 프로젝트 차이

항목	신규 프로젝트	기존 팀 프로젝트
CLAUDE.md	새로 생성	Last sync: 마커 없으면 건너뜀
.claude/hooks/*.sh	새로 생성	@ai-rules:managed 없으면 건너뜀
.claude/settings.json	새로 생성	기존 항목 보존 + hook 추가 (mergeJson)
commitlint.config.mjs	새로 생성	이미 있으면 건너뜀 (ifNotExists)
.husky/pre-commit	새로 생성	이미 있으면 건너뜀 (ifNotExists)
.lintstagedrc.json	새로 생성	이미 있으면 건너뜀 (ifNotExists)
.ai-governance/	새로 생성	새로 생성 (기존에 없던 폴더)
.claude/agents/*.md	새로 생성	새로 생성 (기존에 없던 폴더)

---

통합 절차

1단계 — profile 생성

profiles/_default.yaml을 복사해서 프로젝트에 맞게 수정합니다.

복사cp profiles/_default.yaml profiles/{프로젝트명}.yaml

최소 수정 항목:

복사project: {프로젝트명}
target_path: d:/dev/{프로젝트경로}
github_repo: {org}/{repo}

tooling:
  stack: ts   # ts | py | mixed | docs 중 선택

2단계 — dry-run으로 상태 확인

복사node scripts/sync.mjs --project {프로젝트명} --dry-run

출력 아이콘 의미:

아이콘	의미
✅	이미 최신, 변경 없음
✨	신규 파일 생성 예정
📋	ai-rules 관리 파일, 업데이트 예정
🔒	커스텀 파일 감지, 건너뜀 예정
⏭️	ifNotExists 파일, 이미 존재하여 건너뜀
🔀	settings.json, 병합 예정

🔒 항목이 있다면 커스텀 파일 처리 섹션을 참고하세요.

3단계 — 적용

복사node scripts/sync.mjs --project {프로젝트명} --apply

4단계 — npm 패키지 설치 (tooling 활성화 시)

sync는 설정 파일만 배포합니다. 패키지 설치는 직접 실행해야 합니다.

복사cd {프로젝트경로}
npm install --save-dev husky @commitlint/cli @commitlint/config-conventional lint-staged
npx husky init

---

커스텀 파일 처리

@ai-rules:managed 마커

sync는 .claude/hooks/*.sh 파일을 배포할 때, 대상 파일에 @ai-rules:managed 마커가 있는지 확인합니다.

• 마커 있음 → ai-rules 관리 파일로 인식, 업데이트 허용
• 마커 없음 → 팀이 직접 만든 파일로 보호, 건너뜀

ai-rules가 배포하는 모든 hook 템플릿에는 이 마커가 포함되어 있습니다:

복사#!/usr/bin/env bash
# @ai-rules:managed          ← 이 줄이 있으면 ai-rules가 업데이트 가능
# guard-branch.sh — ...

기존 커스텀 hook을 ai-rules 버전으로 교체하려면

dry-run 출력에서 비교 명령어를 확인해 diff를 먼저 검토합니다:

복사🔒 [dry-run] → .claude/hooks/guard-branch.sh (커스텀 파일 — 적용 시 건너뜀)
   기존: 45줄 | ai-rules 버전: 52줄
   비교: diff "D:/dev/MYPROJECT/.claude/hooks/guard-branch.sh" "output/.../..."

차이를 확인한 뒤 교체를 결정했다면, 파일 2번째 줄에 마커를 추가합니다:

복사#!/usr/bin/env bash
# @ai-rules:managed
# (기존 내용 유지)

이후 --apply를 실행하면 ai-rules 버전으로 교체됩니다.

기존 커스텀 hook의 내용을 유지하면서 ai-rules 관리로 전환하려면

1. 기존 커스텀 로직을 검토합니다
2. ai-rules 버전 파일을 확인합니다 (governance/templates/hooks/{파일명}.sh)
3. 커스텀 로직이 ai-rules 버전에 포함되지 않았다면 governance/templates/hooks/에 반영합니다
4. 파일에 # @ai-rules:managed 마커를 추가하고 --apply를 실행합니다

---

팀 규칙 커스터마이징

CLAUDE.md를 직접 편집하지 마세요. sync 시 덮어써집니다.
팀 고유 규칙은 profile의 overrides: 블록에 작성합니다.

복사# profiles/{프로젝트}.yaml
overrides:
  01-git: |
    ### 우리 팀 추가 Git 규칙
    - PR 제목에 Jira 티켓 번호 필수 (예: [PROJ-123] feat: ...)
    - develop 브랜치 직접 push 금지, PR만 허용
  04-lifecycle: |
    ### 배포 추가 절차
    - 배포 전 QA 체크리스트 확인 (docs/checklist/deploy.md)
    - 스테이징 배포 후 5분 대기 후 main 배포

overrides에 작성한 내용은 sync 시 해당 core 블록 끝에 자동으로 추가됩니다.

---

반복 sync

첫 적용 이후에는 ai-rules가 업데이트될 때마다 아래 명령 하나로 반영됩니다.

복사node scripts/sync.mjs --project {프로젝트명} --apply

내용이 동일한 파일은 건드리지 않으므로 부담 없이 반복 실행할 수 있습니다.
CI에서 자동화하려면 .github/workflows/sync-on-push.yml을 참고하세요.

---

governance 통합 (선택)

AI 코드 교차 검증 시스템을 활성화하려면 profile에 governance: 블록을 추가합니다.

복사governance:
  enabled: true
  preset: solo          # solo | small-team | saas

적용 후 .ai-governance/ 폴더가 생성되며, npm run verify로 교차 검증을 실행할 수 있습니다.
자세한 내용은 docs/guide/GOVERNANCE_INTEGRATION_PLAN.md를 참고하세요.

---

문제 해결

sync 후 CLAUDE.md가 의도한 것과 다르게 생성됐다

CLAUDE.md는 profile에서 조합됩니다. 변경이 필요하면 profile을 수정하고 재sync합니다.

복사# profile 수정 후
node scripts/sync.mjs --project {프로젝트명} --apply

커스텀 파일이 🔒로 건너뛰어져 배포가 안 된다

대상 파일에 @ai-rules:managed 마커가 없어서 보호된 것입니다.
커스텀 파일 처리 섹션을 따라 마커를 추가하세요.

husky hook이 커밋 시 실행되지 않는다

복사cd {프로젝트경로}
npx husky init
# 또는
git config core.hooksPath .husky

settings.json 병합 후 Claude Code에서 hook이 중복 실행된다

.claude/settings.json의 hooks 블록을 직접 확인해 중복 항목을 제거합니다.
이후 sync는 이미 있는 command를 재추가하지 않으므로 다시 발생하지 않습니다.