문서 기여 가이드
Lumie 기술 문서는 lumie-document 레포지토리의 Docusaurus 3 사이트로 제공됩니다. 한국어가 단일 진실 공급원(defaultLocale: 'ko')입니다.
문서 자동 동기화
/commit 스킬이 코드 커밋 시 문서 관련 변경을 감지하면 Docusaurus 문서를 직접 편집합니다. 외부 API 호출이나 별도 CI 없이, Codex 에이전트가 DOC_GEN_RULES.md + DOC_GEN_SIDEBAR_MAP.md를 참조해 docusaurus/docs/<섹션>/*.md를 직접 수정합니다.
SSOT:
- 문서 규칙:
.codex/knowledge/document/DOC_GEN_RULES.md - 사이드바/경로/모듈 매핑:
.codex/knowledge/document/DOC_GEN_SIDEBAR_MAP.md
문서 작성 규칙
필수 프론트매터
모든 문서는 아래 프론트매터를 포함해야 합니다.
---
sidebar_position: <숫자>
title: "<한국어 제목>"
description: "<한국어 설명>"
---
sidebar_position은 기존 번호를 유지합니다. 변경하면 사이드바 순서가 바뀝니다.- 프론트매터
title이 H1을 대체합니다. 문서 본문에 H1(# 제목)을 추가하지 마십시오.
마크다운 규칙
- 헤딩:
##,###사용 (H1은 프론트매터title로만) - 다이어그램: 인라인 Mermaid (
\``mermaid ... ````) - 링크: 상대 경로
.md링크 ([인증 모듈](../backend/auth.md)) - 코드 블록: 언어 태그 필수 (
\``yaml,```java` 등) - MDX 이스케이프: 산문에서 중괄호는
\{,\}로 이스케이프
용어 통일
| 사용 | 금지 |
|---|---|
| 모듈 | 서비스, 마이크로서비스 (백엔드 컴포넌트 지칭 시) |
| 헥사고날 아키텍처 | 포트-어댑터 패턴 |
| 멀티테넌시 | 멀티-테넌시, multi-tenancy (산문에서) |
디렉터리 구조
docusaurus/
├── docs/
│ ├── architecture/ # 아키텍처 개요, 기술 스택
│ ├── backend/ # 백엔드 모듈 문서
│ ├── frontend/ # 프론트엔드 아키텍처
│ ├── ai/ # Worker 서비스 (grading, report, analysis, chatbot)
│ ├── infra/ # 인프라 (cluster, gitops, security, observability)
│ ├── data-model/ # 데이터 모델
│ ├── erd/ # ERD 다이어그램
│ ├── dev/ # 개발 환경 (이 문서 포함)
│ └── troubleshooting/ # 트러블슈팅 기록
├── sidebars.js
├── docusaurus.config.js
└── static/img/
새 카테고리를 추가할 때는 sidebars.js에도 등록하십시오. 기존 카테고리는 자동 검색됩니다.
문서 추가하기
docusaurus/docs/<카테고리>/<slug>.md파일 생성- 필수 프론트매터 작성 (
sidebar_position,title,description) - 내용 작성 (H1 없이
##부터 시작) - 이미지는
docusaurus/static/img/에 저장하고/img/...로 참조 /commit스킬로 커밋
로컬 미리보기
cd docusaurus
npm run start # 개발 서버 (포트 3000)
npm run build # 프로덕션 빌드 확인
npm run serve # 빌드 결과 서빙
에이전트 · 스킬 에코시스템
Lumie의 root .codex/는 워크스페이스 자동화의 단일 진실 공급원입니다. Root .codex가 workflow skill, cross-repo reference, lint gate, custom agent, repo knowledge, path-scoped rules, hook을 소유하고, 각 서브레포는 자기 repo의 AGENTS.md와 제품 코드만 소유합니다.
/commit 스킬
커밋 시 실행되는 단일 진입점입니다. Staged diff sweep, 문서 영향도 확인, 커밋 메시지 검증을 순차 실행합니다.
/commit → sweep.sh → docs-impact gate → message validation → git commit
라우팅 모델
Lumie repo 라우팅은 root reference로 관리합니다. /ship 또는 /execute가 작업 repo를 판단한 뒤, .codex/routing/repos/*.md와 필요한 Execute reference를 읽고 specialist agent를 호출합니다.
Repo별 필수 reference:
| 레포 | Reference |
|---|---|
lumie-backend | .codex/routing/repos/backend.md |
lumie-frontend | .codex/routing/repos/frontend.md |
lumie-worker | .codex/routing/repos/worker.md |
lumie-infra | .codex/routing/repos/infra.md |
lumie-document | .codex/routing/repos/document.md |
주요 에이전트:
| 에이전트 | 용도 |
|---|---|
backend-scaffolder | 백엔드 모듈/기능 scaffold |
frontend-scaffolder | 프론트엔드 FSD feature/entity scaffold |
worker-scaffolder | FastAPI worker service scaffold |
backend-reviewer | Java/Spring 코드 리뷰 |
frontend-reviewer | TypeScript/Next.js 코드 리뷰 |
worker-reviewer | Python/FastAPI 코드 리뷰 |
infra-validator | YAML/Kubernetes 매니페스트 검증 |
backend-migration-author | Flyway 마이그레이션 작성 |
backend-migration-reviewer | Flyway 마이그레이션 검토 |
api-contract-checker | BE-FE API 계약 일관성 확인 |
codex-md-author | .codex/ 문서 작성/수정 |
스킬 (slash-commands)
Cross-repo skill은 .codex/skills/*/SKILL.md로 정의됩니다. Repo-specific 실행 절차는 root reference로 관리합니다. 주요 스킬:
| 스킬 | 용도 |
|---|---|
/ship | Intake부터 Learn까지 표준 10단계 개발 harness |
/intake | 의도, repo scope, work type, stop condition 정리 |
/discover | graphify-first 영향 범위 탐색 |
/spec | 큰 작업의 acceptance criteria 작성 |
/design | 구조, 소유권, 도메인 용어 결정 |
/plan | edit/test/review scope와 병렬화 경계 작성 |
/execute | specialist agent와 reference 기반 구현 |
/verify | 테스트, 계약, 성능, 보안 검증 선택 |
/review | specialist reviewer와 risk scoring |
/commit | 커밋 (sweep + 리뷰 + doc-sync 포함) |
/learn | post-mortem, rule drift, .codex/ 유지보수 |
개인 스킬
서드파티 재사용 스킬은 Lumie repo가 아니라 개인 $CODEX_HOME/skills에 둡니다.
| 스킬 | 위치 |
|---|---|
shadcn | $CODEX_HOME/skills/shadcn |
vercel-react-best-practices | $CODEX_HOME/skills/vercel-react-best-practices |
vercel-composition-patterns | $CODEX_HOME/skills/vercel-composition-patterns |
폴리레포 구조
Lumie는 폴리레포(polyrepo)입니다. 각 서브폴더는 독립 Gitea 레포로 커밋됩니다.
| 레포 | 설명 |
|---|---|
lumie-backend | Spring Boot 모듈러 모놀리스 |
lumie-frontend | Next.js + FSD |
lumie-worker | FastAPI 워커 서비스 |
lumie-infra | ArgoCD, K3s, Tekton GitOps |
lumie-document | Docusaurus 문서 사이트 (이 레포) |
lumie-team | OpenClaw 에이전트 |
lumie-graph | graphify AST 크로스레포 지식 그래프 |
.codex | 워크스페이스 Codex 설정 |