기획 협업 스킬 가이드

이게 무엇인가

기획 산출물이 메신저·메일·개인 드라이브로 흩어지면 누구는 v1, 누구는 v2 를 본다. 이 레포는 명세를 한 곳(specs/)에 두고, 기능마다 영구 고정 링크 하나를 발급한다. 명세가 바뀌면 같은 주소의 내용이 갱신되므로 링크를 다시 뿌릴 일이 없다.

1. 설정

팀원 — 쓰는 사람 (최초 1회, 5분)

git clone https://github.com/<소유자>/DaouClaude.git
cd DaouClaude
python3 .claude/skills/spec-hub/scripts/spechub.py version   # 사본 위치·버전

읽기만 하는 사람

할 일이 없다. 링크만 받으면 된다. 레포 권한도, 계정 생성도 필요 없다. 사내 이메일로 접근이 걸러진다. 전체 목록 페이지를 받아 두면 기능이 늘어도 링크를 추가로 받을 필요가 없다.

관리자 — 레포당 1회

한 사람이 한 번만 하면 되고, 그 뒤로는 아무도 만지지 않는다.

호스팅 (Cloudflare Pages)

• Pages 프로젝트를 만들고 .spechub.json 의 base_url · project 를 그 주소·이름으로 맞춘다.
• GitHub Actions Secrets 에 CLOUDFLARE_ACCOUNT_ID · CLOUDFLARE_API_TOKEN 을 넣는다.
• 접근 제한이 필요하면 Cloudflare Access 로 도메인(@daou.co.kr)을 건다.

화면에서 글을 쓰게 하려면 (문의·답변·점검 체크)

정적 페이지에는 저장할 곳이 없으므로, 같은 도메인의 Pages Function 이 받아 git 에 커밋한다. Cloudflare → Settings → Environment variables:

curl -s https://<도메인>/api/ask
# {"ok":true,"repo":"owner/repo","branch":"main"}  ← 설정 확인 (값은 내보내지 않는다)

문의 알림 받을 사람

.spechub.json 의 notify 에 GitHub 계정을 적는다. 그 계정은 이 레포의 협업자여야 지정이 먹는다.

"notify": {
  "assignees": ["Davidjeong1"],
  "labels": ["문의"],
  "by_feature": { "DOP-20230": ["gildong"] }   // 기능별로 다르면
}

2. 실행

누구의 작업이든 끝은 커밋 · PR 이다. 수동 게시 단계는 없다.

기획의 4단계 — 명세를 조금이라도 바꿨다면 끝까지 밟는다

화면에서 바로 할 수 있는 것 세 가지

레포를 몰라도 된다. 링크를 연 사람이 그 자리에서 쓰고, 결과는 git 에 남는다.

과거 버전 스냅샷에서는 전부 읽기 전용이다 — 지나간 시점에 글을 다는 것은 말이 되지 않는다.

명령어 (직접 돌릴 때)

S=".claude/skills/spec-hub/scripts/spechub.py"
python3 $S new DOP-19102 "연차정책 관리"   # 새 기능 폴더 + 로우파이 목업 템플릿
python3 $S status                          # 전체 현황 (버전·상태·점검·문의)
python3 $S lint                            # REQ-ID 정합성
python3 $S build specs/<기능>               # hub.html 미리보기 (배포 없이)
python3 $S review specs/<기능>              # 배포본과 지금 소스의 차이
python3 $S bump specs/<기능> --level minor --author 이름 --note "REQ-003 …"

R=".claude/skills/spec-review/scripts/specreview.py"
python3 $R pack                            # 검토 문서 한 번에 (CI 가 쓰는 것)
python3 $R publish specs/<기능>             # 퍼블 대조 (publish/ 가 있을 때)
python3 $R diff specs/<기능> --from v0.7.0 --to v0.8.0
python3 $R check                           # 눌러야 아는 것 · 명세/점검 누락

3. 관리

버전과 스냅샷

변경이력의 각 버전은 그 시점 스냅샷({고정URL}/v0.6.0/)으로 남는다. 목업까지 그때 것이라 "그 버전에서 화면이 어땠는지" 를 눌러볼 수 있다. 스냅샷에는 과거 버전임을 알리는 배너가 뜬다 — 옛 명세를 최신으로 착각한 채 개발이 시작되는 것을 막는다.

검토 문서는 자동으로 붙는다

명세를 쓰면 spec-review 가 읽는 사람을 위한 문서를 만들어 같은 링크의 목차에 끼워 넣는다. 새 링크가 생기지 않는다.

목차는 기획 / 문서 / 바깥 문서 / 요구사항 네 묶음이고, 문서 는 다섯 자리로 고정되어 있다. 파일명 앞의 번호가 곧 그 자리다. 요구사항은 수십 개가 되기도 해서 접힌 채로 시작하고, 눌러서 펼친다(선택은 사람별로 기억된다).

같은 번호로 파일을 직접 넣으면 그 자리는 생성물 대신 그것이 들어간다(생성물 표식이 없으면 덮어쓰지 않는다). 파일이 없는 자리는 목차에 준비 중 으로 남아, 무엇이 빠졌는지 그대로 보인다. 기능 지도·퍼블 대조·변경점·동작 점검표는 목차에 상시로 걸지 않는다 — 필요할 때 map·publish·diff·check 로 따로 뽑아 본다. 목차의 바깥 문서 에는 QA 진행 문서 링크가 걸린다 — 기능마다 다르면 spec.md 의 qa_url, 팀이 하나로 관리하면 .spechub.json 의 qa_url.

문의가 오면 담당자에게 알림이 간다

GitHub 은 커밋으로 알림을 보내지 않는다(레포를 Watch 해도 오는 것은 이슈·PR 뿐이다). 그래서 문의 커밋을 이슈로 옮긴다.

열린 이슈 목록이 곧 미답변 문의 목록이 된다. 따로 관리할 것이 없다. 알림이 오지 않으면 받는 사람의 GitHub → Settings → Notifications 에서 Participating 이 Email 로 켜져 있는지 본다.

CI 는 세 가지를 한다

main 브랜치에 Require a pull request before merging + 명세 검사를 필수 체크로 걸어 두면, 검사를 통과하지 않은 변경이 배포되는 일이 없어진다.

충돌은 두 곳에서만 난다

역할마다 만지는 파일이 달라 대체로 충돌이 없다. 예외 둘:

1. CHANGELOG.md — 새 항목이 늘 맨 위에 들어가 두 사람이 동시에 bump 하면 겹친다. 두 항목을 모두 남기고 버전 순서만 정리한 뒤 spec.md 의 version 을 맨 위 항목과 맞춘다. lint 가 불일치를 잡는다.
2. 같은 요구사항 블록 — 도구가 아니라 오너가 정할 문제다. owners.기획 을 채워 두는 이유가 이것이다.

qna.md 는 묻는 쪽이 파일 끝에 이어 붙이고 기획이 그 아래 답을 다는 구조라 서로 다른 줄에 쓴다 — 위에 끼워 넣으면 그때부터 충돌이 난다.

스킬이 업데이트되면

스킬은 레포에 들어 있으므로 git pull 이 곧 업데이트다. 스킬만 바뀐 경우 (명세는 그대로인데 허브 화면 구성이 바뀐 경우)에는 bump 하지 않는다 — 기획 변경이 아니다. 병합하면 CI 가 다시 만들어 올린다.

문제 해결

지켜야 할 다섯 줄

즉 읽기는 링크, 쓰기는 레포다. 그 두 줄만 지키면 나머지는 자동으로 따라온다.