Maintenance

Overview

pnpm test
pnpm check
pnpm build
git diff --check

Conventions

• Formatter: 공백 4칸 · lineWidth: 180 · Biome와 EditorConfig
• Files: kebab-case · 컴포넌트 Pg, Wg, Ui 레이어 접두사
• Imports: @/ · 같은 폴더 CSS 부수효과 import만 ./
• Ownership: 소유자 전용 파일 _ · _function, _type, _constant 역할 폴더
• Functions: 이름 붙인 const 화살표 · 블록 본문 · 명시적 반환
• Props: 구조분해 없이 props.* 접근
• Classes: scope_slug__element--modifier · 조합은 clsx
• Comments: 명사구 · 목적·계약·제약 · 구현 반복 설명 제거
• Language: 제목·짧은 라벨은 영어 우선 · 본문·설명은 한국어 · Writing
• Commits: 영어 동사로 시작 · AI 도움을 받은 제목의 마지막은 | aa · 저장소 루트 AGENTS.md·CLAUDE.md

Lint coverage

Biome: 포맷, import, 타입·이름·레이어 규칙. Stylelint: CSS 클래스, 선택자, 중첩, 토큰 규칙. no-literal-fallback.grit: ??, || 오른쪽의 리터럴 검사. Biome와 Grit의 커스텀 진단 메시지는 영어.

의미·소유권·주석·접근성은 수동 리뷰 대상. 린트만으로 컨벤션 충족 판정 불가.

Grid renderer

src/util/mermaid/render-flow.js: blueprint 계열과 공유한 JS 구현. Biome 제외 이유: 기존 렌더링 알고리즘과 diff 대조. 주석은 프로젝트 문체 사용 · 실행 로직 변경 시 별도 확인.

Browser checks

• 문서 전체: 1600px Light·Dark, 1024px, 390px
• 가로 넘침 · 끊긴 문서·section 링크 · 처리되지 않은 흐름도 · 콘솔 오류
• 시스템 테마 변경 반영 · TOC의 현재 section·subsection
• 데스크톱의 문서 탐색 첫 묶음 라벨·h1 글자 위쪽 시작선 · 사이트 이름은 그 위
• Architects Daughter Regular의 실제 표시 · 로컬 글꼴 선요청·캐시 · 긴 사이트 이름의 한 줄 말줄임
• 데스크톱의 사이트 이름 고정 · 이름 아래 문서 목록 스크롤 · 공유 사이드바의 목차 끝까지 이동해도 사이트 이름 유지
• 본문 최대 폭 900px · 넓은 화면의 중앙 정렬 · 화면 축소 시 오른쪽 여백을 먼저 줄인 뒤 본문 축소 · 짧은 화면에서도 사이드바 마지막 링크와 키보드 포커스가 보이는지 확인
• 모든 화면에서 문서 탐색 아래 TOC · 데스크톱의 공유 사이드바 스크롤 · 모든 subsection 표시
• 1px 트리의 가지·줄기 연결 · 마지막 항목의 줄기 종료 · 중첩·긴 제목의 첫 줄 연결 · 현재 항목까지 가로 가지·세로 경로 강조 · 아래 항목과 다른 묶음은 기본 선색 유지
• 본문·TOC 자동 번호 없음 · 직접 쓴 번호는 유지 · 긴 제목 첫 줄의 트리 연결
• 현재 문서·TOC의 공통 굵기 500 · hover·키보드 포커스의 세로 경로와 밑줄 · 탐색 종료 후 현재 경로 유지 · 하위 목차의 상위 경로 연결
• 본문 양쪽 1px 보더·32px 패딩 · 사이드바와 간격 32px · 사이드바 자체 패딩·세로 보더 없음 · 긴 제목의 줄바꿈과 컬럼 폭 유지
• 스크롤 중 본문 끝까지 양쪽 보더 유지 · 모든 데스크톱의 문서 탐색·TOC 공유 스크롤 · 작은 화면의 세로선·본문 패딩 해제
• 한국어 hash · 폰트 로드 후 위치 · 키보드 포커스
• 문서 묶음: 읽는 순서 · 모든 문서 공개 · 아이콘 없는 텍스트 · 키보드 링크 이동
• 방문한 문서의 보라색 · 현재 문서 강조 우선 · 새로고침과 뒤로 가기 후 방문색 유지
• 문서 탐색·사이트 이름 hover의 글색·굵기 유지와 밑줄 · hover 링크색의 레일 · 현재 문서의 레일 유지
• Note·Details: 기본 접힘·{open}·중첩 · Enter·Space · 숨은 제목의 hash 공개
• 부품 문법 오류: 제목·본문·닫힘·속성 · 파일·줄 표시
• 모바일: 첫 화면에서 본문 표시 · 스크롤 중 메뉴 버튼 유지 · 드로어 열기·닫기·Escape·배경 클릭
• 드로어: Tab 포커스 범위 · 닫기 후 버튼 복귀 · 내부 스크롤과 배경 잠금 · 1024px 전환 시 모달·포커스·잠금 정리
• 드로어 목차: 닫은 뒤 제목 포커스·강조 · 고정 헤더 아래 도착 · 같은 hash 재클릭·Details 공개
• JavaScript 비활성 상태의 본문·TOC와 모바일 기본 목록
• 상대 Markdown 링크: query·hash 보존 · README 홈·참조 링크·중첩 경로
• dev: 추가·수정·삭제 · 잘못된 문서 후 정상 복구

Packaging and release

pnpm pack

패키지 설치 후 별도 폴더에서 dev, build, preview 확인. 정적 사이트는 문서 폴더의 dist 전체 배포. 사이트 루트 경로 기준 · Deployment. 첫 공개 버전 0.1.0의 지원 범위는 dev, build, preview. init은 별도 예정 작업.

공개 전 위 검증 명령을 모두 통과하고, 패키지에 CLI·CSS·클라이언트 스크립트·폰트·favicon·라이선스가 포함되는지 확인.

Automatic publishing

워크플로는 .github/workflows/ci.yml, .github/workflows/release.yml. Release는 main에 포함된 커밋, 태그와 일치하는 package.json 버전, 해당 버전의 CHANGELOG.md 항목과 README 설치 명령 확인. vX.Y.Z 정식 버전만 지원. prerelease는 별도 정책을 추가한 뒤 사용. 설치 검증은 저장소 밖의 새 프로젝트에서 실행. CLI·CSS·클라이언트·글꼴·favicon·라이선스와 README 포함 여부 확인.

Trusted Publisher setup

npm 패키지 설정의 Trusted Publisher에 한 번 등록.

GitHub가 발급하는 OIDC 자격 증명 사용. 별도 NPM_TOKEN이나 매번의 로그인·2FA 입력 불필요. GitHub-hosted runner, Node.js 24와 npm 12.2.0으로 배포. 패키지 사용자의 Node.js 최소 버전은 22 유지. 설정 기준은 npm Trusted Publishing.

Release steps

1. package.json 버전을 올리고 CHANGELOG.md에 변경 사항 기록.
2. 최상위 README.md와 language/README.ko.md의 설치 버전·지원 버전 갱신.
3. 검증 명령 실행. pnpm build가 templates/document/README.md도 동기화.
4. 변경 파일만 커밋하고 main에 push. CI와 Pages 결과 확인.
5. 해당 커밋에 같은 버전의 태그를 만들고 push.

다음 공개 버전이 0.1.2인 경우:

git tag -a v0.1.2 -m "Release v0.1.2"
git push origin v0.1.2

태그 push 후 Release Actions 실행 결과 확인. npm 배포가 성공한 뒤 GitHub Release 생성. 이미 npm에 같은 버전이 있다면 패키지의 integrity가 일치할 때만 재배포를 건너뛰고 GitHub Release 작업을 이어감. 내용이 다르면 실패. 게시한 버전은 수정하거나 덮어쓰지 않고 다음 버전으로 공개.

main의 README 변경은 GitHub와 문서 사이트에 먼저 반영. npm README와 홈페이지 주소는 새 패키지 버전을 배포할 때 반영. 공개 후 npm에서 패키지를 새 프로젝트에 설치해 같은 명령 확인. 다른 프로젝트의 고정된 의존성 버전은 별도 갱신.

Roadmap

진행 순서, 단계별 산출물과 완료 기준은 Roadmap. 다음 작업은 Blueprint 샘플을 기준으로 blueprint의 전용 정보 구조와 표현 정의.