실행 가능 항목 전체 정리

```bash npm run <script> ```

guide docs/guide/COMMANDS.md

ai-rules에서 실행할 수 있는 모든 명령어·스킬·MCP 툴·스크립트를 한 곳에 정리한다.

1. npm scripts (`package.json`)

npm run <script>

Sync

명령	설명
`npm run sync`	모든 프로젝트 output/ 생성 (타겟 적용 없음)
`npm run sync:apply`	output/ 생성 + 타겟 프로젝트에 실제 적용
`npm run sync:dry`	dry-run — 변경될 파일만 미리 확인 (실제 쓰기 없음)

프로젝트 생성

명령	설명
`npm run new`	새 프로젝트 프로필 생성 대화형 CLI
`npm run scaffold`	스타터킷으로 새 프로젝트 전체 스캐폴딩
`npm run onboard`	기존 프로젝트 온보딩 가이드 실행

검증

명령	설명
`npm run validate`	ai-rules 설정 파일 유효성 검증

보고

명령	설명
`npm run scrum`	현재 날짜 데일리 스크럼 리포트 출력
`npm run scrum:save`	리포트 파일 저장 (`reports/daily/YYYY-MM-DD.md`)
`npm run scrum:notify`	저장 + Telegram 알림 전송
`npm run scrum:all`	전체 프로젝트 대상 스크럼
`npm run scrum:all:notify`	전체 프로젝트 + 알림
`npm run scrum:ai`	AI 에이전트가 분석한 스크럼 생성
`npm run scrum:ai:notify`	AI 스크럼 + 알림
`npm run report:weekly`	주간 보고서 출력
`npm run report:weekly:save`	주간 보고서 저장 (`reports/weekly/YYYY-WNN.md`)
`npm run report:weekly:notify`	저장 + 알림
`npm run report:weekly:all`	전체 프로젝트 주간 보고
`npm run report:weekly:ai`	AI 분석 주간 보고
`npm run report:weekly:ai:notify`	AI 주간 보고 + 알림

기타

명령	설명
`npm run ai:logs`	AI 대화·터미널 로그 Obsidian vault로 내보내기 (PowerShell)
`npm run permissions`	`.claude/settings.json` 권한 UI 편집기 실행

2. Claude Code 슬래시 명령어 (`.claude/commands/`)

Claude Code CLI에서 /명령어 형식으로 호출.

/planning

개발 흐름

명령	한 줄 설명	자동 진입 조건
`/planning`	작업 계획 수립 — Plan Mode 진입, 범위·의존성 분석	변경 예상 20줄+ 또는 3파일+
`/design-doc`	ADR/RFC/설계 문서 작성 — G2 게이트 통과	DB/API 변경 포함 시
`/tdd`	RED-GREEN-REFACTOR 사이클 강제 — 테스트 선행 개발	—
`/refactoring`	Blast Radius 분석 → 단계별 안전한 구조 개선	—
`/debugging`	반복 오류 체계적 진단 → stash 스냅샷 → 1회 수정 검증	동일 오류 2회+

커밋 & PR

명령	한 줄 설명	자동 진입 조건
`/commit`	브랜치 확인 → diff 검토 → 커밋 → push 안전 프로세스	—
`/code-review`	PR 전 2단계 리뷰 (spec-reviewer → code-reviewer)	에이전트 PR 생성 전 필수
`/pr-create`	충돌 확인 → PR 생성 → 브랜치 상태 보고	—

보고

명령	한 줄 설명	산출물
`/daily-scrum`	일일 현황 리포트 생성	`reports/daily/YYYY-MM-DD.md`
`/weekly-report`	주간 보고서 생성	`reports/weekly/YYYY-WNN.md`
`/logs`	현재 프로젝트 AI 작업 로그 Obsidian vault로 수집	—
`/logs-all`	전체 프로젝트 AI 작업 로그 일괄 수집	—

통합·관리

명령	한 줄 설명
`/sync`	ai-rules core/extensions → 모든 adapter 출력 재생성
`/jira`	Jira 티켓 조회·검색·코멘트·상태 전환·작업 시작 (MCP 우선, REST 폴백)
`/self-improve`	위반 패턴 분석 → 스킬/변명 방지 룰 보강 → 교차 검증 자기 개선 루프

3. MCP 서버 툴 (`mcp-server/`)

Claude Code claude_desktop_config.json 또는 .mcp.json에 서버 등록 후 자연어로 호출.

서버: `ai-rules`

툴 이름	설명	주요 파라미터
`scaffold_project`	스타터킷으로 새 프로젝트 스캐폴딩 + ai-rules 문서 복사 + Git init	`name` (필수), `stack` (기본: react-fastapi-postgres), `copy_output_docs`, `git_init`

사용 예

"meetflow 프로젝트를 next-fastapi-postgres 스택으로 만들어줘"
→ scaffold_project(name="meetflow", stack="next-fastapi-postgres")

4. Node.js CLI 직접 실행

npm scripts로 래핑되지 않은 도구들. node 명령으로 직접 실행.

프로젝트 스캐폴딩

node cli/scaffold.mjs --name <project-name> [options]

옵션	기본값	설명
`--name`, `-n`	필수	프로젝트명 (kebab-case)
`--stack`, `-s`	`react-fastapi-postgres`	스택 프리셋
`--no-docs`	false	ai-rules 문서 복사 건너뜀
`--no-git`	false	Git 초기화 건너뜀

외부 의존성 0 — 폐쇄망/오프라인 환경에서도 실행 가능.

파이프라인 상태 확인

node cli/pipeline.mjs status --project <path>
node cli/pipeline.mjs next --project <path> [--agent-output <file>]
node cli/pipeline.mjs check-gate G1 --project <path>

서브명령	설명
`status`	현재 프로젝트의 G1~G4 게이트 상태 출력
`next`	다음 수행할 스텝 추천
`check-gate <G1~G4>`	특정 게이트 통과 조건 확인

5. Governance 스크립트 (`governance/`)

언제 필요한가: 팀 프로젝트에서 AI 3-Agent 크로스 검증을 실제로 실행할 때.
일반 개발 작업에서는 sync.mjs만으로 충분하며 이 스크립트들은 선택적.

초기화 및 검증

# 기존 프로젝트에 거버넌스 설정 파일 생성 (sync.mjs의 수동 대안)
node governance/scripts/init.mjs --target <프로젝트 경로> [--preset solo|small-team|medium-team|large-team] [--dry-run]

# .ai-governance/config.yaml 구조 유효성 검증
node governance/scripts/validate.mjs [--target <프로젝트 경로>]

# 거버넌스 설정 파일 상태 헬스체크 (LLM 호출 없음)
node governance/scripts/gate-health-check.mjs [project-path]

신뢰 점수 및 평가

# 에이전트 누적 신뢰도 점수 계산
node governance/scripts/trust-score.mjs [--project <name>] [--since <YYYY-MM-DD>]

# governance 검증을 테스트 케이스로 실행
node governance/scripts/eval-runner.mjs [--dry-run]

크로스 검증 오케스트레이터 (핵심)

# AI 3-Agent Round 크로스 검증 실행
node governance/orchestrator/index.mjs \
  --target <project> \
  --diff <diff-file> \
  [--rounds 3] \
  [--output json|text] \
  [--verbose]

옵션	설명
`--target`	검증 대상 프로젝트 경로
`--diff`	검증할 diff 파일 경로
`--rounds`	검증 라운드 수 (기본: 3)
`--output`	출력 형식 — `json` 또는 `text`

이 명령은 .ai-governance/config.yaml과 .ai-governance/agents.yaml이 있어야 실행 가능.
없으면 먼저 init.mjs 또는 sync.mjs --apply로 설정 파일을 생성할 것.

빠른 참조 — 상황별

상황	명령
새 프로젝트 시작	`npm run scaffold` 또는 `node cli/scaffold.mjs`
기존 프로젝트에 ai-rules 적용	`npm run sync:dry` → 확인 → `npm run sync:apply`
오늘 뭐했는지 리포트	`npm run scrum` 또는 `/daily-scrum`
커밋하기	`/commit`
PR 올리기	`/code-review` → `/pr-create`
반복 오류 발생	`/debugging`
새 기능 구현	`/planning` → `/tdd` → `/commit` → `/pr-create`
거버넌스 상태 확인	`node governance/scripts/gate-health-check.mjs`