ai-rules 온보딩 가이드

| 문서 | 내용 | |------|------| | [workspace-ecosystem.md](../../extensions/workspace-ecosystem.md) | 전체 지도 — 디렉토리 분류, 규칙 체계, 데이터 흐름 | | 이 문서 |

guide docs/guide/ONBOARDING.md

AI 코딩 에이전트의 규칙을 한 곳에서 관리하고, 모든 프로젝트에 동기화하는 시스템.

1. 먼저 읽을 것

문서	내용
workspace-ecosystem.md	전체 지도 — 디렉토리 분류, 규칙 체계, 데이터 흐름
이 문서	처음 시작하는 방법

2. ai-rules가 하는 일

core/규칙 + extensions/확장 + profiles/프로파일
    ↓ sync.mjs
각 프로젝트의 CLAUDE.md, .cursor/rules/, hooks 등

한 줄 요약: 규칙을 한 곳(core/, extensions/)에서 편집하고, sync로 모든 프로젝트에 배포한다.

3. 전체 구조

ai-rules/
├── core/            ← 글로벌 규칙 (보안, git, 코드, 라이프사이클)
├── extensions/      ← 도메인/프로젝트별 확장 규칙
├── profiles/        ← 프로젝트별 조합 설정 (YAML)
├── adapters/        ← 도구별 출력 변환 (Claude Code, Cursor, Windsurf)
├── agents/          ← 에이전트 정의 (planner, builder, reviewer)
├── governance/      ← hook 템플릿
├── scripts/         ← sync.mjs, 유틸리티
└── docs/            ← 이 문서들

데이터 흐름

core/ + extensions/
    ↓ profiles/*.yaml이 조합 지정
    ↓ adapters/가 도구별 포맷으로 변환
output/ (중간 결과)
    ↓ sync --apply
각 프로젝트 (CLAUDE.md, .cursor/rules/, .claude/hooks/)

4. 5분 퀵스타트

설치

cd D:/dev/ai-rules
npm install

현재 상태 확인

node scripts/sync.mjs --dry-run    # 모든 프로젝트의 변경 사항 미리보기

실제 적용

node scripts/sync.mjs --apply      # 모든 프로젝트에 규칙 배포

특정 프로젝트만

node scripts/sync.mjs --project meetflow --apply

5. 나는 어떤 유형?

A. 개인 프로젝트만 사용

profiles/ 에 프로젝트 프로파일 생성 (.example.yaml 복사)
target_path에 프로젝트 경로 설정
core:, extensions: 에 필요한 규칙 선택
sync --apply로 배포

# profiles/my-project.yaml
project: my-project
target_path: "D:/dev/my-project"
core:
  - 00-critical
  - 01-git
  - 03-security
extensions: []

B. 회사 프로젝트 추가

회사별 공통 규칙이 필요할 때:

extensions/에 회사 공통 규칙 파일 생성 (예: sk-company-rules.md)
프로파일에서 해당 extension 추가
자세한 절차는 RULE_TIERS.md "회사 추가 절차" 참조

참고: dev-bs/ 프로젝트는 ai-rules가 아닌 cc-sync 체계를 사용한다. workspace-ecosystem.md의 "규칙 체계 이중 운용" 참조.

C. 기존 프로젝트에 적용

이미 자체 CLAUDE.md가 있는 프로젝트에 ai-rules를 적용할 때:

→ EXISTING_PROJECT_INTEGRATION.md 참조

핵심: output: .claude/instructions.md로 설정하면 기존 CLAUDE.md와 충돌하지 않는다.

6. 규칙 3계층 이해

ai-rules의 규칙은 3가지 계층으로 분류된다:

계층	뜻	예시
Universal	누가 쓰든 동일	시크릿 금지, force-push 금지
Company	회사/팀이 정함	브랜치 전략, QA 프로세스
Personal	개인 취향	응답 언어, 레이블 형식

자세한 분류표와 승격/강등 방법은 → RULE_TIERS.md 참조

7. 규칙 수정하고 싶을 때

규칙 내용 수정

# 1. core/ 또는 extensions/ 파일 편집
# 2. 변경 확인
node scripts/sync.mjs --dry-run

# 3. 배포
node scripts/sync.mjs --apply

프로젝트에 규칙 추가/제거

profiles/*.yaml의 core: 또는 extensions: 배열을 편집 후 sync --apply.

새 extension 만들기

extensions/my-extension.md 생성 (마크다운)
프로파일의 extensions: 배열에 my-extension 추가
sync --apply

8. FAQ

Q: CLAUDE.md를 직접 편집해도 되나요?

아니요. sync --apply가 덮어씁니다. core/나 extensions/를 편집하세요.

Q: 글로벌 규칙과 프로젝트 규칙이 충돌하면?

프로젝트 CLAUDE.md에 global core(보안/git/workflow)가 우선이 명시되어 있다. 보안/git 규칙은 항상 글로벌이 우선.

Q: 회사 프로젝트(dev-bs/)에서 ai-rules를 쓸 수 있나요?

현재 dev-bs/는 cc-sync 체계를 사용한다. ai-rules를 직접 배포하지 않는다. 글로벌 규칙(~/.claude/CLAUDE.md)의 Universal 계층은 자동으로 적용된다.

Q: sync를 실행하면 뭐가 바뀌나요?

--dry-run으로 먼저 확인. 변경되는 파일:

CLAUDE.md (또는 .claude/instructions.md)
.cursor/rules/*.mdc
.claude/hooks/*.sh
.claude/settings.json
AI-RULES.md

Q: hook이 뭔가요?

에이전트의 행동을 코드로 강제하는 스크립트. 예:

guard-branch.sh — 보호 브랜치 직접 커밋 차단
guard-secrets.sh — 시크릿 커밋 차단
detect-mid-question.sh — 불필요한 질문 패턴 감지

9. 관련 문서

문서	용도
workspace-ecosystem.md	워크스페이스 전체 지도
RULE_TIERS.md	규칙 3계층 분류 + 관리
EXISTING_PROJECT_INTEGRATION.md	기존 프로젝트 적용 절차
project-kickoff.md	신규 프로젝트 체크리스트
HARNESS_ENGINEERING.md	규칙 + Hook 설계 철학