biz-rules

name	biz-rules
description	비즈니스 규칙, 도메인 규칙, 상태 전이 규칙을 하나의 문서로 관리합니다. 변경 이력이 누적됩니다.
when_to_use	비즈니스 규칙 발견했어, 상태 전이 규칙 기록, 코드에서 찾은 도메인 규칙 반영. 일반 지식 반영은 learn.
allowed-tools	Read, Write, Glob, Grep, Bash

역할

프로젝트의 비즈니스 규칙, 도메인 규칙, 상태 전이 규칙, 도메인 점검 카테고리를 하나의 문서로 관리. 코드에 암묵적으로 존재하는 규칙을 명시화하고 변경 이력 누적.

이 문서는 도메인 지식의 단일 source of truth. 다른 스킬들이 참조:

• /review, /cs, /srs, /todo 는 1~3절의 규칙과 상태 전이 참조
• /review, /srs, /qa, /briefing, /deploy-checklist 는 4절의 도메인 점검 카테고리 자동 활용 (Tier 2)

4절이 비어있으면 다른 스킬은 일반 점검 (Tier 1) 만 수행. 채워질수록 도메인 점검 자동 강화.

외부 데이터 의존

데이터	경로	필수/선택	부재 시 동작
프로젝트 컨텍스트	CLAUDE.md	선택	일반 SW 가정으로 진행, [프로젝트 규칙 미확인] 태그
봇 인덱스	bot/INDEX.md 또는 .local.claude/ONBOARDING.md	선택	디렉터리 Glob 으로 fallback
비즈니스 규칙	.local.claude/biz-rules.md	선택	Tier 1(도메인 무관) 점검만 수행
모듈 상세	.local.claude/modules/{name}.md	선택	코드 Grep 직접 fallback
코드 enum/상수	**/*.java, **/*.ts 등	선택	코드 검증 생략, 문서 기반 규칙만
DDL/스키마	**/ddl/*.sql	선택	데이터 모델 검증 생략

파일 구조

기본: 단일 파일 .local.claude/biz-rules.md (CLAUDE.md @ 자동 로드 후보).

분량 임계 (자동 분리):

임계	동작
≤200줄	단일 파일 유지
201~400줄	"곧 분리 권장" 알림 + 사용자 결정 (계속 유지 / 즉시 분리)
>400줄	분리 강제. 핵심만 biz-rules.md 에 남기고 나머지는 biz-rules-detail.md 로 이전

분리 기준:

• biz-rules.md (자동 로드, 핵심): 변경 이력, 1. 상태 전이 규칙 (코드/이름만 표), 4. 도메인 점검 카테고리 (스킬 자동 활용 진입점)
• biz-rules-detail.md (수동 로드, 상세): 2. 비즈니스 규칙 상세, 3. 도메인 규칙 상세, 1. 상태 전이의 상세 설명, 트리거, 코드 레퍼런스

분리 시 작업:

1. biz-rules-detail.md 신규 생성 (frontmatter: category: detail, parent: biz-rules.md)
2. 핵심 파일 상단에 상세: [biz-rules-detail.md](./biz-rules-detail.md) (수동 로드) 안내
3. CLAUDE.md @ 참조는 biz-rules.md 만 유지 (detail 은 @ 금지, 자동 로드 부담)
4. 변경 이력에 분리 사유와 날짜 기록

# {프로젝트명} 비즈니스 규칙

> 마지막 업데이트: YYYY-MM-DD
> 이 문서는 코드에 암묵적으로 존재하는 비즈니스 규칙을 명시적으로 기록합니다.
> `/biz-rules` 스킬로 관리됩니다.

## 변경 이력
| 날짜 | 변경 내용 | 근거 |
|------|----------|------|
| 2026-04-02 | 초기 작성 | 코드베이스 분석 기반 |

---

## 1. 상태 전이 규칙 (예시, 프로젝트 도메인에 맞춰 작성)

> 다음 표 형식으로 프로젝트의 모든 상태 머신을 정의. 아래는 일반적 패턴 예시.

### {승인 워크플로우 상태} (예시)
| 현재 상태 | 허용 전이 | 조건 | 비고 |
|---------|---------|------|------|
| 요청 (REQUESTED) | 검토 / 취소 | 요청자 작성 | |
| 검토 (REVIEWING) | 승인 / 반려 | 검토자 검토 | |
| 승인 (APPROVED) | (종료) | 검토 완료 | 비즈니스 상태 변경 트리거 |
| 반려 (REJECTED) | 요청 | 재요청 가능 | |

### {문서 상태} (예시)
| 현재 상태 | 허용 전이 | 조건 |
|---------|---------|------|
| 임시저장 | 승인중 | 작성자 제출 |
| 승인중 | 배포완료 / 반려 | 승인자 결재 |
| 배포완료 | 개정중 | 개정 요청 시 |
| 개정중 | 삭제 또는 종료 | 폐기 결정 |

### 그 외 도메인 상태 머신
프로젝트의 다른 도메인 (드라이브 파일, 프로젝트, 주문 등) 상태도 같은 형식으로 추가.

---

## 2. 비즈니스 규칙

> 프로젝트 도메인 규칙. 아래 카테고리는 일반적 예시로, 해당하는 것만 채움.

### 멀티테넌트 (있을 시)
- 모든 테이블에 테넌트 키 필수. 조회/저장/삭제 시 반드시 조건 포함.
- 키 없는 쿼리는 전 테넌트 데이터 노출. 최악의 사고.

### 수량/금액 정합성 (제조, 이커머스 등)
- 헤더 합계와 상세 합산은 항상 일치 (서버 검증 로직은 별도 확인 필요)
- 카운터 차감 시 음수 방지 (DB/코드 레벨 강제 여부 확인)

### 승인 워크플로우 연동 (해당 도메인이 있을 시)
- 승인 완료 시 비즈니스 상태 변경. 수정/삭제 차단은 각 모듈 UI 버튼 제어에 의존 (API 공통 차단 로직 유무는 확인 필요)
- 진행 중 문서는 취소 후에만 수정 가능

### 날짜/기간
- 영업일, 공휴일, 휴무일 고려 여부는 도메인별 상이
- 날짜 저장은 DB 시간 함수 기준 (서버 시간)

### 이벤트 발행 (이벤트 기반 아키텍처)
- 상태 변경 시 연관 모듈에 이벤트 발행 필수
- 이벤트 누락 시 모듈 간 데이터 불일치

### 공통 코드값
- 공통 코드는 하드코딩 금지, 코드그룹으로 관리
- 테넌트별로 코드값이 다를 수 있음. 프로파일 오버라이드 확인

---

## 3. 도메인 규칙 (프로젝트 도메인에 맞춰 작성)

### 핵심 비즈니스 프로세스
- 도메인의 핵심 흐름 (예: 이커머스는 주문, 결제, 배송, 완료 순 / 게시판은 작성, 검토, 게시, 보관 순 / SaaS는 가입, 온보딩, 사용, 갱신 순 등)
- 각 단계 간 의존 관계

### 도메인 엔티티 규칙
- 핵심 엔티티의 불변 규칙 (예: 리비전 증가만, 감소 불가)
- 엔티티 간 변환과 자동화 규칙

### 도메인 검사와 검증
- 도메인별 검사 흐름 (예: 품질 검사, 승인 단계, 인증 검증 등)
- 실패 시 후속 처리

---

## 4. 도메인 점검 카테고리 (Tier 2, 스킬 자동 활용)

> 다음 스킬들이 이 섹션을 자동으로 read 하여 **도메인 특화 점검** 을 추가합니다.
> 비어있으면 각 스킬은 **Tier 1 (도메인 무관 일반 점검) 만** 수행합니다.

### 4-1. 도메인 버그 카테고리 (`/review`, `/qa` 활용)

| 카테고리 | 점검 내용 | 왜 위험한지 |
|---------|---------|-----------|
| (예: 승인 연동) | 승인 완료 데이터 수정 차단 점검 | 승인 무결성 |
| (예: 합계 정합성) | 헤더 합계와 상세 합산 일치 | 정산 오류 |
| (예: 리비전 증가만) | 리비전 감소 불가 | 추적성 상실 |
| (예: 코드값 하드코딩 금지) | 공통 코드 하드코딩 금지 | 테넌트 커스터마이징 깨짐 |
| (예: 이벤트 누락) | 상태 변경 시 연관 이벤트 발행 | 모듈 간 정합성 |

### 4-2. 도메인 경계 조건 (`/srs`, `/qa` 활용)

| 카테고리 | 경계값 | 예외 |
|---------|--------|------|
| (예: 수량/금액) | 0, MIN, MAX, 음수, 소수점 정밀도 | 오버플로, 헤더-상세 불일치 |
| (예: 상태 전이) | 첫/마지막 상태, 이미 완료된 상태 재요청 | 허용 안 된 전이 |
| (예: 권한/테넌트) | 다른 테넌트 키 사용자 | 데이터 격리 위반 |
| (예: 동시성) | 같은 데이터 동시 수정 | 덮어쓰기, 카운터 음수 |

### 4-3. 변경 영향 매핑 (`/briefing`, `/deploy-checklist` 활용)

| 변경 유형 | 영향 범위 | 회귀 점검 |
|----------|---------|---------|
| (예: 승인 모듈 변경) | 모든 승인 흐름 | 승인 시나리오 회귀 |
| (예: 멀티테넌트 키 변경) | 모든 모듈 | 데이터 격리 회귀 |
| (예: 공통 코드 추가) | 운영 DB 정합성 | 코드값 누락 점검 |
| (예: 이벤트 발행 변경) | 수신 모듈 전체 | 연쇄 영향 회귀 |
| (예: 상태 전이 변경) | biz-rules 의 상태 전이 표에 등장하는 모든 모듈 | 상태 흐름 회귀 |

---

동작

1. 파일 존재 확인

ls .local.claude/biz-rules.md 2>/dev/null

2. 파일이 없으면 초기 생성

코드베이스를 탐색하여 초기 규칙을 자동 수집:

• CLAUDE.md의 도메인 약어, DTO 규칙
• bot/*.md 또는 .local.claude/ONBOARDING.md 의 워크플로우, 이벤트 흐름
• modules/*.md에서 상태 코드, 비즈니스 로직 관련 내용
• Grep으로 상태 코드, 승인, enum 관련 패턴 검색 (프로젝트 컨벤션)

초기 문서를 생성하고 사용자에게 검토 요청.

3. 파일이 있으면 업데이트

$ARGUMENTS의 입력을 분석하여:

• 새 규칙 추가면 해당 섹션에 추가
• 기존 규칙 수정이면 수정 + 변경 이력에 기록
• 규칙 삭제면 삭제 + 변경 이력에 기록

변경 이력에 항상 날짜, 변경 내용, 근거를 기록.

4. 입력 예시

/biz-rules 승인 완료 후에도 관리자는 수정 가능하다는 걸 알게 됨
/biz-rules 수신 수량이 요청 수량의 110%까지 허용됨 ({고객사} 기준)
/biz-rules {모듈} 처리 시 추적 키 필수, 오늘 CS에서 발견
/biz-rules {모듈}에서 작업 상태 전이가 대기, 진행, 완료, 보류 순서임을 확인함

5. 코드 검증

[1M 활용] 다중 파일 동시 로드:

• 로드: 상태 전이 관련 Service 코드 (Grep 결과 상위), .local.claude/ddl/*.md 관련 테이블 DDL, CLAUDE.md 도메인 약어 및 enum/코드값 정의
• 교차: {코드의 상태 전이 로직 vs 규칙이 명시한 전이 경로 일치}, {DDL 의 컬럼과 제약 vs 수량/금액 정합성 규칙}, {enum 선언 vs 공통 코드값 하드코딩 금지}

새 규칙 추가 시 가능하면 코드에서 검증:

• 상태 전이는 관련 Svc에서 상태 변경 로직 Grep
• 수량 제약은 관련 Mapper XML에서 검증 조건 확인
• 검증 결과를 규칙에 (코드 확인: {파일}:{라인}) 형태로 추가

다른 스킬에서의 참조

이 파일을 참조하는 스킬:

• /review: 도메인 버그 점검 시 상태 전이, 비즈니스 규칙 확인
• /cs: 원인 분석 시 비즈니스 규칙 위반 여부 확인
• /srs: 기능 명세 작성 시 관련 비즈니스 규칙 포함
• /todo: 개발 작업에 주의사항으로 관련 규칙 포함
• /daily-todos: 할 일 구체화 시 관련 규칙 참고

DB 정보 요청

코드에서 추론한 비즈니스 규칙을 실제 DB 데이터로 검증해야 할 때, 사용자에게 확인을 요청한다.

요청이 필요한 상황:

• 공통 코드 테이블의 실제 코드값 목록 확인 (코드그룹별)
• 상태 전이 규칙의 실제 데이터 검증
• 테넌트/고객사별 코드값 차이 확인

요청 형식:

**DB 확인 요청**: 비즈니스 규칙 검증을 위해 아래 쿼리 결과가 필요합니다.

1. [검증 목적]
```sql
SELECT {코드 컬럼}, {이름 컬럼} FROM {코드 테이블} WHERE {그룹 컬럼} = '코드그룹' AND {멀티테넌트 키} = '{테넌트 코드}'

**제약:**
- SELECT만 사용
- 멀티테넌트 키 조건 반드시 포함

**결과 축적:**
사용자가 제공한 DB 정보 중 재활용 가치가 있는 것은 파일로 저장한다.

| 데이터 유형 | 저장 위치 | 조건 |
|------------|----------|------|
| 공통 코드 값 | `.local.claude/biz-rules.md`에 반영 | 기존 규칙에 없는 코드그룹 |
| 테이블 DDL/컬럼 구조 | `.local.claude/ddl/{테이블명}.md` | 규칙 검증 과정에서 확인한 것 |

- 이미 문서에 있는 정보는 중복 저장하지 않음
- 저장 시 출처(날짜, 어떤 규칙 검증에서 확인했는지) 간단히 기록
- 고객사별로 다른 값은 고객사 표시 포함

## 다른 스킬과의 경계

| 질문 | 담당 | 이 스킬에서 |
|------|------|-----------|
| 비즈니스, 상태 전이, 도메인 점검 카테고리 문서를 작성하고 갱신 | **이 스킬** | 핵심 (도메인 지식 SSOT) |
| 이 문서를 진단 루브릭으로 소비 (아키텍처, 기술 진단) | /tech-diagnosis, /analyze-dir | 생산만, 진단과 해석은 위임 |
| 코드 변경의 도메인 버그 점검에 4절 카테고리 활용 | /review | 카테고리 제공만, 리뷰 판정은 위임 |
| 고객사별로 다른 규칙의 상세 관리 | /customer-profile | `(고객사별 상이)` 태그만, 상세는 위임 |

## 제약조건

- 코드에서 확인된 규칙만 기록. 추측 규칙은 `[미확인]` 태그.
- 변경 이력은 삭제하지 않음. 왜 바뀌었는지 추적 가능해야 함.
- 고객사별 차이가 있는 규칙은 `(고객사별 상이)` 태그 + 상세는 `/customer-profile`에서 관리.

## 검증 시나리오

공통 3블록(빈 / 부분 / 풀 데이터)은 **CONTRACT 6-1절** 참조.

### 이 스킬의 고유 실패 시나리오

**[데이터 결함]** 상태 전이 규칙이 코드와 불일치
- 신호: 기존 `biz-rules.md` 4절에 정의된 전이 vs 실제 코드(상태머신, 서비스 레이어)에서 발견한 전이가 상충
- 대응: 두 버전을 양쪽 기술 ("문서는 A에서 B를 거쳐 C / 코드는 A에서 C 직행 허용") 후 사용자 확인 요청, 확인되면 갱신

**[도메인 특수성]** domain-free 프로젝트
- 신호: 인프라, 툴, 라이브러리처럼 비즈니스 도메인 규칙 자체가 없는 프로젝트
- 대응: 4절 카테고리 비움. "이 프로젝트는 도메인 규칙 없음(인프라/툴 성격)" 한 줄 명시 후 1~3절만 작성