standarda-template
새 standarda 프로젝트는 standarda-template(cookiecutter)로 찍어내고, 그 생애는 standarda-devtools가 관리합니다. 이 문서는 코드가 아니라, 프로젝트가 태어나고(생성) → 무엇을 갖고 태어나며(하네스) → 어떻게 일하는가(개발) 의 흐름을 따라갑니다.
1. 생성·복제·삭제
프로젝트의 생성·복제·삭제는 standarda-devtools가 담당합니다.
devtools는 template을 소비하는 별도의 메타 저장소입니다. 그 안에서 Claude Code를 켜면, 실행한 사용자의 홈에 프로젝트를 만들고 정리합니다.
| 단계 | 자동화하는 것 |
|---|---|
| create | 슬러그 도출 · dev+prod 포트 2개 할당(위키 포트 표) · cookiecutter 생성 · GitHub repo · 메모리 심링크. 대화형 setup.sh는 사람에게 인계 |
| clone | 기존 repo를 표준 레이아웃으로 clone · 메모리 심링크 · (Django면) venv·의존성 |
| delete | 파괴적 3단계(조회 → 사용자 확인 → 삭제): 포트 프로세스 · DB · 위키 포트 행 · Apache vhost · 인증서 · Route53 레코드 · GitHub repo · 프로젝트/정적 디렉토리 정리 |
관계는 깔끔합니다. template = 프로젝트가 무엇인가, devtools = 그 생성·복제·삭제입니다.
2. 생성 자동화
create의 핵심인 프로젝트 생성 순간, 사람 손 없이 자동으로 벌어지는 일들입니다.
- 서버 설정에서 호스트를 읽어
ALLOWED_HOSTS에 주입(어느 박스에서 만들어도 하드코딩 없이 그 호스트가 들어감). git init+ 원격 등록 + (인증돼 있으면) 비공개 GitHub repo 생성.- git 훅 강제 층 활성화(
core.hooksPath설정).
이어지는 대화형 setup.sh(사람이 실행)에서는 venv·의존성 설치와 함께 랜덤 시크릿 키를 gitignore된 .env에 생성하고(시크릿은 커밋 안 됨), DB 비밀번호를 실제 psql로 검증한 뒤 DB·마이그레이션·슈퍼유저를 만듭니다.
3. 스킬 · 에이전트 · 훅
프로젝트는 만들어지는 순간 세 가지 하네스(스킬·에이전트·훅)를 물려받습니다. 셋은 서로 포함하는 계층이 아니라 역할이 다르고, 관계가 정해져 있습니다.
| 층 | 무엇 | 역할 |
|---|---|---|
| 스킬(skills) | /develop·/release·/dev 등 |
이름 붙은 작업 절차(슬래시 또는 자연어로 호출) |
| 서브에이전트(agents) | spec-verifier·debug-server-log 등 |
별도 컨텍스트 + 도구 제한으로 위임되는 검증·조사 |
| 훅(hooks) | Claude 도구 훅 + git 훅 | 규칙을 사람이 안 지켜도 자동 차단하는 강제 장치 |
관계를 정리하면 이렇습니다. 스킬이 에이전트를 호출(위임) 합니다(예: /develop이 spec-verifier·merge-master를 부른다). 에이전트는 스킬을 부르지 않습니다. 훅은 누가 부르는 게 아니라 도구 호출·git 동작 시점에 자동 발동해 위반을 막는 가드레일입니다. 즉 스킬→에이전트만 호출 관계이고, 훅은 이벤트로 동작하며, 셋은 서로 포함하지 않습니다.
4. 스킬 카탈로그
프로젝트가 기본으로 갖는 스킬을 용도별로 정리하면 이렇습니다.
| 용도 | 스킬 | 역할 |
|---|---|---|
| 개발 워크플로우 | /develop |
모든 코드 변경의 기본 절차(스펙→구현→검증→문서→머지) |
/dev |
개발 서버 기동 + 첫 실행 시 포트·도메인 자동 세팅 | |
/release |
프로덕션 배포 트리거 | |
| 문서 | /feature-doc |
기능 문서 |
/structure-doc |
구조 문서 | |
/update-skill-agent-list |
스킬·에이전트 목록 재생성 | |
| 고객 산출물 | /client-usage-guide |
사용 가이드(md + Word) |
/client-test-guide |
테스트 체크리스트 | |
/manual |
스크린샷 슬라이드·PDF 매뉴얼 | |
/create-docx |
스타일 Word 생성 | |
| 템플릿 동기화 | /sync-from-template |
템플릿 → 프로젝트 반영 |
/sync-to-template |
프로젝트 공통 파일 → 템플릿 역류 |
5. 서브에이전트
스킬이 부르는 위임 자산들입니다. 대부분 읽기 전용이라 코드를 건드리지 않고 조사·검증만 합니다.
| 에이전트 | 역할 |
|---|---|
spec-verifier |
구현이 docs/specs/{app}.md 스펙과 맞는지 검증(어긋나면 머지 차단) |
merge-master |
스펙·문서 체크리스트·충돌 점검 후 머지·정리 |
debug-server-log |
디버깅 시 서버 로그를 먼저 읽어 traceback을 찾는 강제 선행 단계 |
lesson-finder |
팀 위키 교훈 색인에서 관련 교훈 조회(다른 프로젝트 실수 반복 방지) |
pdf-parser · excel-parser |
샘플로 추출 품질을 시험해 텍스트/비전 전략 결정 |
api-tester · output-verifier |
API 테스트 · 기록 결과를 소스와 대조 검증 |
llm-usage-doc · backlog-manager |
LLM 사용 인벤토리 · 백로그 관리 |
6. 훅
규칙은 사람이 잊어도 훅이 자동으로 막습니다. 두 층이 독립적으로 겹쳐 있습니다.
1층: Claude 도구 훅(Claude가 도구를 부르기 직전 PreToolUse에 발동)
| 훅 | 무엇을 막나 |
|---|---|
| 버그수정 이슈문서 | 커밋 메시지에 버그 키워드가 있는데 docs/issues/ 문서가 없으면 차단 |
| 기능 문서 | 기능 키워드 + 앱 소스 변경인데 docs/specs 또는 docs/features 없으면 차단 |
| except 로거 | except 블록에서 traceback을 버리는 logger.error/warning 신규 추가를 AST로 차단 |
| 스킬 목록·설명 | 스킬·에이전트 변경 시 목록 갱신 없으면, 또는 SKILL.md 설명이 너무 짧으면 차단 |
2층: git 훅(실제 git 동작에서 발동, Claude 훅을 우회해도 잡는 backstop)
| git 훅 | 강제 |
|---|---|
| commit-msg · pre-commit | 버그수정 커밋은 이슈 문서, 스킬 변경은 목록 갱신 포함 |
| pre-push | 지정된 원격(자기 repo) 외 push 차단 |
| reference-transaction · pre-rebase | main은 fast-forward 전용, main rebase 차단 |
git 훅은 작업 트리 바깥에 설치돼(core.hooksPath), reset --hard로도 스스로 꺼지지 않습니다.
7. 개발
물려받은 하네스로 실제 개발을 굴리는 것이 /develop입니다. 모든 코드 변경의 기본 절차이자, 여러 단계를 자동으로 엮는 파이프라인입니다.
worktree 격리 → 스펙 작성(docs/specs/{app}.md, 사이클의 단일 소스) → 구현 → 검증 라운드(spec-verifier 통과할 때까지 머지 차단) → 문서 생성 라운드 → merge-master.
검증은 스펙 통과까지 머지를 막고, 문서·마이그레이션은 자동으로 처리되며, push만 사람 몫으로 남습니다.
마무리
- 핵심 정리: 프로젝트는 devtools로 태어나(생성·복제·삭제), 스킬·에이전트·훅 세 층의 하네스를 물려받아,
/develop으로 개발합니다. 훅은 두 층(Claude 도구 + git)으로 겹쳐 문서 누락·traceback 유실·잘못된 push·main 되감기를 자동 차단합니다. - 주의 사항: git 훅은 작업 트리 밖에 설치돼
reset --hard로도 안 꺼집니다. 규칙을 "잊어도" 막아주는 안전망이지 만능은 아닙니다. - 다음 문서: 이렇게 만든 프로젝트가 개발·빌드·배포될 때 클라우드 인프라에서 어떻게 작동하는지, 아키텍처 구조도와 함께 개발 · 빌드 · 배포 인프라에서 다룹니다.