범용 개발 규칙 체계 (Claude Code Workflow System)

버전: 4.0 | 최종 업데이트: 2026-03-08

이 체계의 목적

Claude Code를 활용한 개발 프로젝트의 일관된 워크플로우를 제공합니다.

• 프로젝트 초기화부터 배포까지 단계별 가이드
• 세션 간 컨텍스트 유지를 위한 인수인계 체계
• 세션 추적 체계 (요약표, 아카이브 색인, 다음 세션 프롬프트)
• 스택 독립적 코딩 규칙 + 스택별 상세 규칙
• 기술 레퍼런스 및 운영 가이드 관리
• 코드 품질 보장을 위한 점검 규칙
• 복잡한 기술 개발을 위한 R&D 워크플로우
• 멀티 터미널을 활용한 병렬 개발 체계
• 스킬 24개 + 에이전트 11개를 통한 워크플로우 자동화
• 3계층 재사용 모델(Design > Code > Page)과 연계한 자산 활용

폴더 구조

dev-rules-system/
│
├── 00-overview/                ← 현재 위치
│   ├── README.md              ← 이 파일
│   ├── architecture.md        ← 5레이어 시스템 구조도
│   └── session-lifecycle.md   ← 세션 라이프사이클 흐름도
│
├── 01-global-rules/           ← 모든 프로젝트 공통 규칙
│   └── CLAUDE.md              → ~/.claude/CLAUDE.md에 복사
│
├── 02-project-template/       ← 새 프로젝트 시작 시 복사
│   ├── CLAUDE.md              → 프로젝트 루트에 복사 (풀뿌리 트리)
│   └── docs/                  → 프로젝트에 복사
│       ├── commands/          ← 명령어 모음 (13개 파일)
│       ├── rules/             ← 상세 규칙 (10개 파일)
│       │   └── coding-stacks/ ← 스택별 코딩 규칙
│       ├── status/            ← 현재 상태 + 세션 요약표
│       ├── handover/          ← 인수인계서 + next-dev-prompt
│       ├── references/        ← 기술 레퍼런스 (DB스키마, API 등)
│       ├── guides/            ← 운영 가이드 (개발서버, 배포 등)
│       ├── logs/              ← 작업 로그 아카이브
│       └── locks/             ← 파일 잠금
│
├── 03-dev-templates/          ← 스택 설정, MCP 가이드, 초기화 파일
│   ├── auth/                  ← 인증 (Supabase)
│   ├── ui/                    ← 공통 UI 컴포넌트
│   ├── api/                   ← API 유틸리티
│   ├── mcp/                   ← MCP 가이드 + 프리셋 (19서버 카탈로그 연동)
│   └── _init/                 ← .gitignore, .env.example
│
├── 04-dev-stages/             ← Phase 1~8 단계별 가이드
│   ├── README.md              ← 단계 개요
│   ├── phase1-init.md ~ phase8-session.md
│   └── checklist.md           ← 전체 체크리스트
│
├── 05-code-quality/           ← 점검 규칙
│   ├── react-best-practices/  ← React 45개 룰
│   ├── web-design-guidelines/ ← UI/UX 가이드
│   └── ai-coding-limits/      ← AI 코딩 한계와 협업 전략
│
├── 06-tech-rd/                ← 복잡한 기술 개발용
│   ├── README.md              ← Spike→POC→Integration 워크플로우
│   ├── commands.md            ← R&D 명령어
│   ├── python-rd-*.md         ← Python R&D 전략/계약/검증/프로토콜
│   └── templates/             ← Python R&D 템플릿
│
├── 07-parallel-dev/           ← 병렬 개발 (3-터미널 동시 개발)
│   ├── README.md              ← 병렬 개발 개요 및 Phase 0~3
│   ├── parallel-dev-*.md      ← 계약, 의존성, 충돌, 통합 등 10개 문서
│   └── templates/             ← 병렬 개발 템플릿
│
└── 99-appendix/
    ├── all-commands.md        ← 전체 명령어 한눈에
    ├── troubleshooting.md     ← 문제 해결
    └── 범용_개발규칙_체계_정리.md ← 체계 종합 정리

빠른 시작

1. 글로벌 규칙 설정 (최초 1회)

cp 01-global-rules/CLAUDE.md ~/.claude/CLAUDE.md

2. 새 프로젝트 시작

# 방법 A: 수동 복사
cp -r 02-project-template/* ./
cp -r 03-dev-templates ~/dev-templates
cp -r 05-code-quality ~/dev-templates/rules

# 방법 B: 스킬 사용 (권장)
/kdysetting    # 프로젝트 개발 체계 자동 셋팅
/kdypick       # 재사용 코드 선택 적용

3. Claude Code에서 명령어 사용

세션 시작.                    # 또는 자연어로 직접 요청
프로젝트 초기화해줘.          # 또는 /kdysetting
이 프로젝트 React 성능 점검해줘.
세션 종료.                    # 또는 /cs

5개 레이어 시스템

우선순위: 프로젝트 CLAUDE.md > 글로벌 CLAUDE.md 실행 계층: 규칙(L1~L4)이 What을 정의, 스킬/에이전트(L5)가 How/Who를 실행

8단계 개발 플로우

→ 상세: 04-dev-stages/

코드 품질 규칙

React Best Practices (45개 룰)

Web Design Guidelines

접근성, 폼 UX, 포커스, 애니메이션, 다크모드 점검

AI 코딩 한계 (NEW)

AI가 잘하는 것/못하는 것, 자주 범하는 실수, 협업 Best Practices

→ 상세: 05-code-quality/

정제 프로세스

코드 품질을 단계적으로 향상시키는 4단계 정제 체계:

초벌 개발 (Phase 1-4) → 1차 정제 (구조) → 2차 정제 (품질) → 최종 정제 (보안)

→ 상세: refining-process.md

기술 R&D 워크플로우

복잡한 기술 개발 시:

Tech Spike → POC → Integration → Iteration
(실험)      (검증)   (통합)       (고도화)

→ 상세: 06-tech-rd/

병렬 개발 워크플로우

3개 터미널을 활용한 동시 개발 체계. 계약 정의 → 3병렬 개발 → 순차 통합.

→ 상세: 07-parallel-dev/README.md

문서 관리 규칙

개요 파일은 가볍게, 상세는 전용 파일로 분리. 파일 크기 제한 및 네이밍 컨벤션.

→ 상세: doc-management-rules.md

스킬/에이전트 연동

규칙 체계의 각 영역에 대응하는 자동화 스킬:

→ 전체 스킬 목록: 루트 CLAUDE.md → 에이전트 목록: 04-agents/

← 체계 목차