Files

hyeonggil f6cb59ac8b 📝 docs: CLAUDE.md 파일 및 관련 문서 작성 규칙 추가

2026-04-19 21:59:39 +09:00

6.4 KiB

Raw Permalink Blame History

name, description

name	description
project-init	현재 프로젝트를 분석하여 .claude/project/ 하위 문서(overview.md, conventions.md, architecture.md)를 실제 내용으로 채웁니다. 사용자가 "/init", "프로젝트 초기화", "프로젝트 문서 작성해줘" 등을 요청할 때 트리거됩니다.

Project Init — 프로젝트 문서 자동 작성

이 skill 은 현재 Git 저장소를 탐색하여 .claude/project/ 하위 세 파일을 실제 프로젝트 정보로 채웁니다.

언제 사용하는가

/init 실행 시
.claude/project/*.md 가 템플릿 상태(placeholder 가 남아 있음)일 때
새로운 프로젝트에 gameservice-fe-agent 를 처음 적용할 때

작업 순서

1. 환경 파악 (읽기 전용)

아래 파일들을 순서대로 읽어 프로젝트 정보를 수집한다. 파일이 없으면 건너뛴다.

파일 / 명령	수집 정보
`package.json`	프로젝트 이름, 의존성, 스크립트, 패키지 매니저
`pnpm-lock.yaml` / `yarn.lock` / `package-lock.json`	패키지 매니저 확정
`nuxt.config.ts` / `next.config.` / `vite.config.`	프레임워크, 모듈, 빌드 설정
`tsconfig.json`	TypeScript strict 여부
`tailwind.config.*`	CSS 프레임워크
`.eslintrc.` / `eslint.config.`	린터 설정
`README.md`	서비스 설명, 팀 정보
`app/` / `src/` / `pages/` 디렉토리 구조	레이어, 주요 기능
`server/api/` 또는 `src/api/`	외부 의존성, API 패턴
`stores/` / `composables/`	상태 관리 패턴

2. 기존 문서 상태 확인

.claude/project/overview.md, conventions.md, architecture.md 를 읽어 이미 작성된 내용이 있으면 덮어쓰지 않고 비어 있는 섹션만 채운다.

placeholder(<...>) 가 남아 있는 줄 → 채움 대상
실제 내용이 작성된 줄 → 유지

3. 사용자 확인 후 작성

탐색이 끝나면 아래 요약을 사용자에게 먼저 보여준다.

📋 감지된 프로젝트 정보
  이름: <name>
  프레임워크: <framework>
  패키지 매니저: <pm>
  언어: TypeScript (strict: <yes/no>)
  CSS: <css>
  상태관리: <state>
  테스트: <test>

✍️ 아래 파일을 업데이트하려고 합니다:
  - CLAUDE.md                          (제목 · 주요 명령어 · 주의사항)
  - .claude/project/overview.md
  - .claude/project/conventions.md
  - .claude/project/architecture.md

진행할까요? (y/n)

사용자가 y 또는 별도 지시 없이 진행을 허락할 때만 파일을 수정한다.

4. 각 파일 작성 규칙

CLAUDE.md

루트 CLAUDE.md 는 Claude 가 대화 시작 시 항상 읽는 파일이므로, 매번 하위 파일까지 탐색하지 않아도 되는 핵심 정보만 간결하게 기재한다.

제목 (# <프로젝트 이름>): package.json 의 name 필드로 교체 예) # epic7-esports → # Epic7 Esports E7WC name 이 slug 형태면 사람이 읽기 좋은 표기로 변환한다.
## 주요 명령어 섹션 (필수 추가): package.json 의 scripts 에서 아래 유형을 추출하여 그룹별로 정리한다. 주석은 스크립트 이름만으로 의도를 알기 어려울 때만 달고, 뻔한 것은 생략한다.
```
## 주요 명령어

# 개발 서버
<dev 계열 스크립트>

# 빌드
<build 계열 스크립트>

# 린트 / 포맷
<lint 계열 스크립트>
```
- dev, start, local 등 → 개발 서버 그룹
- build, build:* → 빌드 그룹
- lint, lint:*, format, prettier → 린트 / 포맷 그룹
- test, test:* → 테스트 그룹 (존재할 때만)
- 나머지 잡다한 스크립트는 포함하지 않는다.
## 주의사항 섹션 (선택 추가): 프로젝트 고유의 "함정"이 될 수 있는 항목을 2-4개 이내로 요약한다. 소스는 conventions.md 의 금지 사항 섹션 + CSS/API 탐색 결과. 없으면 이 섹션은 추가하지 않는다.
```
## 주의사항

- CSS: <탐색 결과에 따라 기재. 예: Tailwind 아님, SCSS 사용 — Tailwind 클래스 금지>
- API: <API 호출 패턴 금지/허용 규칙>
- 환경: <.env 파일 분기 규칙>
```
이미 제목이 실제 이름으로 바뀌어 있거나 섹션이 존재하면 덮어쓰지 않고 유지한다.

overview.md

서비스 > 이름: package.json 의 name 필드 사용
서비스 > 설명: README.md 첫 단락 또는 package.json 의 description
기술 스택: 탐색에서 수집한 실제 값으로 채움. 모르면 <확인 필요> 유지
주요 기능: pages/ 또는 app/pages/ 디렉토리 목록을 기반으로 유추
참고 문서: README.md 에 링크가 있으면 옮기고, 없으면 <확인 필요> 유지

conventions.md

디렉토리 규칙: 실제 디렉토리 구조에서 확인된 폴더만 설명, 없는 항목은 삭제
API 호출 창구: composables/ 또는 api/ 디렉토리 패턴에서 유추
테스트 러너 / 위치: package.json devDependencies + vitest.config.* 참고
공통 지침과 다른 점이 없다면 "공통 지침을 따른다" 로 간단히 기재

architecture.md

레이어 구조: 실제 디렉토리 목록으로 ASCII 다이어그램을 업데이트
상태 관리 가이드: 탐색에서 확인한 라이브러리로 표의 권장 위치를 채움
외부 의존성: server/api/ 파일명 또는 useFetch 호출에서 유추. 불확실하면 <확인 필요>

5. 완료 안내

✅ 문서 업데이트 완료

변경된 파일:
  - CLAUDE.md
  - .claude/project/overview.md
  - .claude/project/conventions.md
  - .claude/project/architecture.md

다음 단계:
  1) 각 파일에서 <확인 필요> 항목을 직접 채워주세요.
  2) 변경 사항을 커밋해 주세요:
     git add CLAUDE.md .claude/project/
     git commit -m "docs: 프로젝트 초기 문서 작성"

주의사항

파일 삭제 금지: 기존 .claude/project/*.md 는 내용을 수정할 뿐 절대 삭제하지 않는다.
추측 표시: 확실하지 않은 정보는 (추정) 을 붙이고, 사용자가 쉽게 찾아 수정할 수 있게 한다.
최소 변경: 이미 올바르게 작성된 섹션은 건드리지 않는다.
커밋 금지: 파일 수정 후 git commit 은 사용자 명시 요청이 없으면 실행하지 않는다.

6.4 KiB Raw Permalink Blame History