아키텍처 구조도
버전: 4.0 | 최종 업데이트: 2026-03-08 5레이어 시스템과 개발 플로우 시각화
1. 5레이어 시스템
┌─────────────────────────────────────────────────────────────────────────┐
│ Claude Code 실행 │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ L1. 글로벌 규칙 [낮은 우선순위] │
│ ~/.claude/CLAUDE.md │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ • 모든 프로젝트 공통 규칙 │ │
│ │ • 초기화 명령어 정의 │ │
│ │ • 공용 템플릿 위치 안내 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ L2. 공용 템플릿 [재사용 코드] │
│ ~/dev-templates/ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ auth/ │ │ ui/ │ │ api/ │ │
│ │ Supabase │ │ Button │ │ fetcher │ │
│ │ 인증 코드 │ │ Input │ │ 유틸 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ L3. 프로젝트 규칙 [높은 우선순위] │
│ 프로젝트/CLAUDE.md │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ • 프로젝트 특화 규칙 │ │
│ │ • 풀뿌리 문서 트리 │ │
│ │ • docs/ 참조 링크 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ L4. 프로젝트 문서 [상세 규칙] │
│ 프로젝트/docs/ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ commands/ │ │ rules/ │ │ status/ │ │ handover/ │ │
│ │ 명령어 │ │ 상세규칙 │ │ 현재상태 │ │ 인수인계 │ │
│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │references/ │ │ guides/ │ │ logs/ │ │
│ │ 기술참조 │ │ 운영가이드│ │ 작업로그 │ │
│ └────────────┘ └────────────┘ └────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ L5. 스킬/에이전트 [자동화 실행] │
│ 03-skills/ + 04-agents/ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 스킬 24개 │ │ 에이전트 11개│ │ MCP 19서버 │ │
│ │ /cs, /kdy* │ │ code-reviewer│ │ 카탈로그 │ │
│ │ 자동화 실행 │ │ 역할별 위임 │ │ 외부 연동 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
2. 우선순위 흐름
┌──────────────────┐ 덮어쓰기 ┌──────────────────┐
│ │ ───────────────▶ │ │
│ L1. 글로벌 규칙 │ │ L3. 프로젝트 규칙 │
│ (기본값) │ ◀─────────────── │ (우선 적용) │
│ │ 상속 │ │
└──────────────────┘ └──────────────────┘
예시:
- 글로벌: "주석은 한국어" → 모든 프로젝트에 적용
- 프로젝트: "이 프로젝트는 영어" → 해당 프로젝트만 영어
3. 이동된 섹션 참조
아래 다이어그램은 각 전용 파일에서 확인:
| 주제 | 참조 위치 |
|---|---|
| 8단계 개발 플로우 | → 상세: 04-dev-stages/README.md |
| 세션 라이프사이클 | → 상세: session-lifecycle.md |
| 기술 R&D 워크플로우 | → 상세: 06-tech-rd/README.md |
| 코드 품질 점검 흐름 | → 상세: 05-code-quality/README.md |
| 정제 프로세스 흐름 | → 상세: refining-process.md |
| 폴더 구조 | → 상세: README.md |
| 병렬 개발 워크플로우 | → 상세: 07-parallel-dev/README.md |
| 스킬/에이전트 목록 | → 상세: 루트 CLAUDE.md |
| MCP 서버 카탈로그 | → 상세: 02-reusable-code/14-mcp-catalog/ |
| 3계층 재사용 모델 | → 상세: 02-reusable-design/, 02-reusable-code/, 02-reusable-page/ |
4. 파일 관계도
┌─────────────────────────┐
│ CLAUDE.md │
│ (프로젝트 루트) │
└────────────┬────────────┘
│ 참조 (풀뿌리 트리)
┌──────────┬────────────┼────────────┬──────────┐
▼ ▼ ▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ docs/rules/ │ │docs/status/ │ │docs/handover│ │docs/referen-│ │docs/guides/ │
│ │ │ │ │ │ │ ces/ │ │ │
│• _index.md │ │• current.md │ │• _index.md │ │• _index.md │ │• README.md │
│• coding.md │ │ (세션요약) │ │• README.md │ │• _TEMPLATE │ │• dev-server │
│• coding- │ │ │ │• next-dev- │ │• 프로젝트별 │ │• deployment │
│ stacks/ │ │ │ │ prompt.md │ │ 레퍼런스 │ │ │
│• ... │ │ │ │• 인수인계서 │ │ │ │ │
│ │ │ │ │ │ │ │ │ │
│ [상세 규칙] │ │ [현재 상태] │ │ [인수인계] │ │ [기술 참조] │ │ [운영가이드]│
└─────────────┘ └──────┬──────┘ └─────────────┘ └─────────────┘ └─────────────┘
│
┌─────────────┼─────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│docs/commands│ │ docs/logs/ │ │ docs/locks/ │
│ │ │ │ │ │
│• _index.md │ │• _index.md │ │• README.md │
│• 01-xxx.md │ │• YYYY-MM.md │ │• *.lock │
│• 02-xxx.md │ │ 또는 │ │ │
│• ... │ │ sessions- │ │ │
│ │ │ MMDD.md │ │ │
│ [명령어] │ │ [작업 로그] │ │ [파일 잠금] │
└─────────────┘ └─────────────┘ └─────────────┘
5. 체계 구성 요소 관계도
┌─────────────────────────────────────────────────────────────────────────────┐
│ 범용 개발 규칙 체계 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Global Rules │ │ Dev Templates │ │ Quality Rules │ │
│ │ (글로벌 규칙) │ │ (개발 템플릿) │ │ (품질 규칙) │ │
│ │ │ │ │ │ │ │
│ │ ~/.claude/ │ │ ~/dev-templates │ │ ~/dev-templates │ │
│ │ CLAUDE.md │ │ /auth │ │ /rules │ │
│ │ │ │ /ui │ │ │ │
│ │ • 공통 원칙 │ │ /api │ │ • React 45룰 │ │
│ │ • 초기화 규칙 │ │ /stacks │ │ • Web Design │ │
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
│ │ │ │ │
│ └──────────────┬──────┴─────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────┐ │
│ │ Project Template │ │
│ │ (프로젝트 템플릿) │ │
│ │ │ │
│ │ 각 프로젝트/ │ │
│ │ ├── CLAUDE.md │ │
│ │ └── docs/ │ │
│ │ ├── commands/ (13개) │ │
│ │ ├── rules/ (10개) │ │
│ │ │ └── coding-stacks/│ │
│ │ ├── status/ │ │
│ │ ├── handover/ │ │
│ │ ├── references/ │ │
│ │ ├── guides/ │ │
│ │ ├── logs/ │ │
│ │ └── locks/ │ │
│ └─────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────┐ │
│ │ Development Stages │ │
│ │ (개발 단계) │ │
│ │ │ │
│ │ Phase 1~8 │ │
│ └─────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 03-skills/ │ │ 04-agents/ │ │ 02-reusable-*/ │ │
│ │ (스킬 24개) │ │ (에이전트 11개) │ │ (3계층 재사용) │ │
│ │ │ │ │ │ │ │
│ │ /cs, /kdy* │ │ code-reviewer │ │ design/ │ │
│ │ 워크플로우 │ │ security- │ │ code/ (훅,유틸) │ │
│ │ 자동화 │ │ reviewer 등 │ │ page/ (Footer) │ │
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
│ └──────────────┬──────┴─────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────┐ │
│ │ MCP 서버 카탈로그 (19개) │ │
│ │ 14-mcp-catalog/ │ │
│ │ /kdymcp 관리 │ │
│ └─────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
6. 배포 위치 관계도 (홈 디렉토리)
~/
├── .claude/
│ └── CLAUDE.md ← 글로벌 규칙 (모든 프로젝트 공통)
│
├── dev-templates/ ← 재사용 템플릿 저장소
│ ├── auth/ ← 인증 템플릿
│ │ ├── supabase/
│ │ └── components/
│ ├── ui/ ← UI 컴포넌트
│ ├── api/ ← API 유틸리티
│ ├── stacks/ ← 스택별 설정
│ ├── rules/ ← 코드 품질 규칙
│ │ ├── react-best-practices/ ← React 45개 룰
│ │ └── web-design-guidelines/ ← UI/UX 가이드
│ ├── docs/
│ └── _init/ ← 초기화 파일
│
├── .claude/
│ └── skills/ ← 글로벌 스킬 (kdysync로 동기화)
│
└── my-project/ ← 개별 프로젝트
├── CLAUDE.md ← 프로젝트별 규칙 (풀뿌리 트리)
├── docs/
│ ├── commands/ ← 명령어 모음 (13개 파일)
│ ├── rules/ ← 상세 규칙 (10개 파일)
│ │ └── coding-stacks/ ← 스택별 코딩 규칙
│ ├── status/ ← 현재 상태 + 세션 요약표
│ ├── handover/ ← 인수인계서 + next-dev-prompt
│ ├── references/ ← 기술 레퍼런스
│ ├── guides/ ← 운영 가이드
│ ├── logs/ ← 작업 로그 아카이브
│ └── locks/ ← 파일 잠금
├── public/images/ ← 이미지 구조
└── src/ ← 소스 코드
# 재사용 자산 저장소 (00-general-pro 내)
00-general-pro/
├── 02-reusable-design/ ← 디자인 토큰, CSS, Tailwind, 에셋
├── 02-reusable-code/ ← 훅 48개, 유틸, UI 44개, 패턴 등
├── 02-reusable-code-python/ ← Python 재사용 코드
├── 02-reusable-page/ ← 페이지 레벨 컴포넌트 (Footer 4종)
├── 03-skills/ ← 스킬 24개 정의
└── 04-agents/ ← 에이전트 11개 정의