# {프로젝트명} 비즈니스 규칙 > 마지막 업데이트: 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 의 상태 전이 표에 등장하는 모든 모듈 | 상태 흐름 회귀 | ---

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

**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절만 작성

데이터

경로

필수/선택

부재 시 동작

프로젝트 컨텍스트

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

선택

데이터 모델 검증 생략

임계

동작

≤200줄

단일 파일 유지

201~400줄

"곧 분리 권장" 알림 + 사용자 결정 (계속 유지 / 즉시 분리)

>400줄

분리 강제. 핵심만 biz-rules.md 에 남기고 나머지는 biz-rules-detail.md 로 이전

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

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

biz-rules

역할

외부 데이터 의존

파일 구조

동작

1. 파일 존재 확인

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

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

4. 입력 예시

5. 코드 검증

다른 스킬에서의 참조

DB 정보 요청

역할