Next.js 16 App Router와 MDX 기반으로 구축된 개인 개발 블로그입니다.
Git 서브모듈로 컨텐츠를 관리하며 SSG(Static Site Generation) 방식으로 최적화된 성능을 제공합니다.
- Framework: Next.js 16 App Router (Turbopack 빌드, React Compiler 활성)
- UI Runtime: React 19
- Language: TypeScript 6 (strict mode)
- Styling: Tailwind CSS 4 · shadcn/ui · next-themes
- Icons: lucide-react
- Content: MDX (Git Submodule
contents/) · Shiki 코드 하이라이팅 - Type Safety: Zod (frontmatter·API runtime validation)
- Testing: Vitest · React Testing Library · MSW · Playwright
- Runtime: Vercel KV (
/api/views조회수, fail-soft fallback) - Quality: ESLint 9 · Prettier 3 · Lefthook 2
3-Layer (app → features → shared 단방향):
src/
├── app/ — 라우팅, metadata, providers
├── features/ — 9개 도메인 (posts, tags, series, search, views, comments, theme, lightbox, about)
└── shared/ — components, ui(shadcn), styles, seo, config, utils, hooks, types, modules
contents/ — MDX 콘텐츠 (Git Submodule)
docs/ — PRD, ROADMAP, TASKS, AI_WORKFLOW_GUIDE
.claude/ — AI 에이전트 하네스 (agents, skills, rules, commands, hooks)
3 Laws (.claude/rules/project-structure.md):
app → features → shared단방향 의존 (역방향 금지)shared는features를 모름- feature 간 직접 import 금지 —
app/에서 조립 또는shared/로 승격
pnpm dev # 개발 서버 (port 3100)
pnpm build # 프로덕션 빌드 (Turbopack)
pnpm lint # ESLint
pnpm format # Prettier 포매팅
pnpm test # Vitest (Unit + Integration)
pnpm test:e2e # Playwright E2E (5 spec)포트: 개발 서버는 3100 (Next.js 기본 3000이 아님).
- SSG-first — 런타임 CMS·서버 검색·클라이언트 캐시(TanStack Query) 도입하지 않음. 유일한 런타임 API는
/api/views(Vercel KV). - TDD (Red→Green→Refactor) + Testing Trophy (Integration ~60%)
- Page-First Skeleton — M1에서 더미 데이터로 전 페이지 UI 완성 후 단계적 실데이터 교체
- 콘텐츠는 Git Submodule —
contents/저장소 분리로 소스와 글의 커밋 이력 독립 - 한글 slug 영역별 분리 — 포스트는 영문 강제(도구·CDN 호환), 태그·시리즈는 한글 허용 + 공백→hyphen 정규화
- Fail-soft 조회수 — KV 미설정/장애 시 GET=0, POST=silent skip (페이지 500 차단)
| 문서 | 용도 |
|---|---|
docs/TASKS.md |
M0~M7 태스크 체크리스트 (199/199 완료) |
docs/ROADMAP.md |
마일스톤별 상세 — 검증 기준, Entry/Exit |
docs/PRD_PRODUCT.md |
제품 스펙 — FEAT, US, 성공 지표 |
docs/PRD_TECHNICAL.md |
기술 계약 — MOD, RT, ADR, 데이터 모델 |
docs/AI_WORKFLOW_GUIDE.md |
Claude Code 멀티 에이전트 하네스 동작 원리 |
CLAUDE.md |
Claude Code 온보딩 · Progressive Disclosure |
이 프로젝트는 Claude Code 기반 컴파운드 엔지니어링 하네스를 갖추고 있다.
사용자가 자연어로 요청하면 내부에서 전문 에이전트 팀이 자동 구성되어 6단계 품질 사이클을 돈다.
"M0-01 진행해줘"
→ blog-dev 스킬 트리거
→ TeamCreate (Feature 트랙 팀 구성)
→ PLAN → EXECUTE → REVIEW(핑퐁 3회) → VALIDATE → DOCUMENT → SYNTHESIZE
→ 사용자 보고 (변경 파일·사이클 통계·빌드 결과)
| 트랙 | 트리거 예시 |
|---|---|
| Feature | M0-06 진행, 검색 기능 만들어줘 |
| Content | React 19 use 훅 포스트 초안 |
| GC | Week 0 GC, 청소해줘, 하네스 평가 |
| Docs | TASKS 체크 맞춰줘, ROADMAP 진행률 |
- 15개 에이전트 (
orchestration·developer·planning·quality·content·documentation) - 15개 스킬 (오케스트레이션 3 · 도메인 작업 4 · 참조 지식 8 —
ai-seo·programmatic-seo·seo-audit추가) - 17개 규칙 (아키텍처·스타일·품질·하네스·아이콘·REVIEW 강제·No-Fallback·Comments)
- 9개 슬래시 커맨드 (수동 단일 작업용)
상세 동작은 docs/AI_WORKFLOW_GUIDE.md 참조.
- 자동:
src/코드, 테스트,docs/TASKS.md체크박스,CHANGELOG.md - 사용자 승인 필수: 의존성 추가(
package.json)·아키텍처 변경·PRD 수정·Git 쓰기 작업 (commit·push·PR·머지·tag 모두 명시 요청 필수,.claude/rules/workflow.md"Git 쓰기 절대 금지 규칙" 참조)
main ← 프로덕션 릴리스 (보호)
develop ← 기본 통합 브랜치 (모든 feature PR의 base)
feature/M{n}-{슬러그} ← 마일스톤 단위 개발
1 마일스톤 = 1 feature 브랜치.
새 마일스톤 첫 태스크 진입 시 orchestrator가 리모트 최신 develop으로부터 feature/M{n}-* 브랜치 생성을 제안한다 (사용자 승인 후 실행).
마일스톤 완료 시 develop으로 PR, merge commit 또는 rebase merge (squash merge 금지 — atomic commits 보존).
PR 생성 전 반드시 origin/main (또는 base 브랜치)을 develop에 merge해서 conflict 사전 해소.
# 의존성 설치 + 서브모듈 (contents) 초기화
git clone --recurse-submodules https://github.com/chan9yu/dev-blog.git
cd dev-blog
pnpm install
# 개발 서버
pnpm dev
# → http://localhost:3100
# 프로덕션 빌드 테스트
pnpm buildchan9yu.dev — Vercel 자동 배포 (main 머지 → 프로덕션, develop PR → Preview).
- Framework Preset: Next.js
- Build Command:
pnpm build(Turbopack) - Output:
.next/ - Environment Variables (선택, 조회수 활성화 시):
KV_REST_API_URL,KV_REST_API_TOKEN—@vercel/kv자동 인식- 미설정 시 빌드·렌더 정상 동작, 조회수만
0으로 표시
- 품질 게이트: 로컬
lefthookpre-commit (Prettier · ESLint · tsc) + Vercel 빌드 시 typecheck
MIT License - 자세한 내용은 LICENSE 파일을 참조하세요.