standarda-template: 표준 양식

1. 무엇인가

새 프로젝트를 만들 때 복사해 쓰는 표준 양식입니다(실제로는 cookiecutter 라는 도구로 동작합니다). 매번 로그인·설정·폴더 구조·자동화 도구를 처음부터 만들지 않도록, 완성된 시작점을 통째로 제공합니다.

문서 양식을 복사해 새 문서를 만드는 것과 같습니다. 빈 양식을 복사한 뒤 프로젝트 이름·설정만 채워 넣으면, 매번 같은 구조의 프로젝트가 나옵니다.

2. cookiecutter = 복사 + 빈칸 채우기

cookiecutter 는 그냥 복사(cp)가 아니라, 복사하면서 이름·설정을 끼워 넣어 주는 도구입니다. 실제로 일어나는 3단계:

1. 물어봄:   "프로젝트 이름이 뭐야?"        → 당신: "Skyrocket Agent"
2. 복사함:   template 폴더를 통째로 복사
3. 채워넣음:  복사하면서 빈칸(변수)들을 답으로 치환

치환의 예:

[template 원본]                        [찍혀 나온 결과]
{{cookiecutter.project_slug}}/    ──▶   skyrocket_agent/
DB_NAME = "{{...db_name}}"        ──▶   DB_NAME = "skyrocket_agent"
TIME_ZONE = "{{...timezone}}"     ──▶   TIME_ZONE = "Asia/Seoul"

이 "빈칸 목록"이 바로 cookiecutter.json 파일입니다(프로젝트명·slug·DB명·타임존 등).

Q. {{cookiecutter.project_slug}} 는 예시 프로젝트명이야?

A. 아닙니다. {{ }} 는 "여기에 값을 채워라"는 빈칸(자리표시)입니다. 두 이름의 차이를 알아 두세요. - project_name = 사람이 읽는 이름 → "Skyrocket Agent" (띄어쓰기·대문자 OK) - project_slug = 그걸 컴퓨터용으로 변환 → skyrocket_agent (소문자, 공백→_)

slug 는 띄어쓰기가 있으면 안 되는 곳(폴더명·DB명·깃허브 repo명)에 쓰는 버전입니다.

3. template 은 직접 개발하는 곳이 아니다 (가장 중요)

Q. template 에서 직접 개발하는 거야?

A. 아닙니다. 이게 가장 중요한 구분입니다.

standarda-template/          ~/skyrocket_agent/  (찍어낸 결과물)
  (표준 양식·원본)    ──▶       (내 프로젝트)
 깨끗하게 유지                ← 여기서 기능 추가·수정

• 고유 기능은 찍어낸 프로젝트 폴더(~/skyrocket_agent)에 추가합니다.
• template(원본 양식) 은 손대지 않고 그대로 둡니다. cookiecutter 로 한 번 찍고 나면 원본과 남남이 되기 때문입니다(그래서 template 을 고쳐도 이미 찍어낸 프로젝트는 바뀌지 않습니다. 버그가 아니라 의도된 설계입니다).

그럼 template 은 언제 고칠까요? 딱 한 경우: "앞으로 새로 만들 프로젝트들이 물려받을 공통 뼈대를 개선" 할 때입니다.

그래서 CLAUDE.md 에 "공통 파일을 고치면 template 에도 반영(sync)하라"는 규칙이 있습니다.

4. 찍어내면 딸려오는 것

{{cookiecutter.project_slug}}/ 폴더 안이 통째로 복사되어 새 프로젝트가 됩니다. 주요 구성:

{{cookiecutter.project_slug}}/
├── setup.sh              # 생성 후 첫 셋업 자동화(venv·DB·migrate)
└── src/
    ├── manage.py         # Django 조종석
    ├── {프로젝트}/settings/   # 설정 3분할(base/local/production)
    ├── accounts/ profiles/ emails/ sms/ projects/   # 공통 앱 5종(이미 완성)
    ├── utils/            # 공통 헬퍼(예외·응답·검증 등)
    ├── requirements.txt  # 설치 목록(Django + core + LLM 라이브러리)
    ├── templates/ static/   # 화면(HTML)·CSS/JS
    ├── docs/  e2e_tests/    # 문서 규격·기본 테스트
    └── .claude/          # 자동화(skills·agents·hooks)

• 공통 앱은 이미 완성돼 있습니다: 로그인·프로필·이메일/SMS 인증 등. 새 프로젝트는 고유 기능에만 집중하면 됩니다.
• .claude/ 의 자동화 도구(/dev·/release·pdf-parser·ui-tester 등)가 처음부터 장착된 채 시작합니다.

5. 생성 직후 자동으로 일어나는 일 (hook)

cookiecutter 는 찍어낸 직후 뒷정리 스크립트(hooks/post_gen_project.py)를 자동 실행합니다. 즉 "복사만" 하는 게 아니라:

cookiecutter 실행
├─ 1. 질문 → 답
├─ 2. 폴더 복사 + 빈칸 치환
└─ 3. 뒷정리 자동 실행
     ├─ ALLOWED_HOSTS 에 이 서버 IP 자동 주입
     ├─ git init + 원격 연결 + private repo 생성 시도
     └─ '다음 단계' 안내 출력

그다음 사용자가 ./setup.sh 를 실행하면: venv 생성 → pip install(Django+core) → SECRET_KEY 생성 → DB 생성·migrate → 관리자 계정 생성까지 이어집니다.

마무리

• 핵심 정리: template 은 cookiecutter 로 프로젝트 뼈대를 찍어내는 표준 양식입니다. 복사하면서 빈칸(이름·설정)을 채우고, 한 번 찍고 나면 원본과 남남이 됩니다(그래서 고유 기능은 찍어낸 프로젝트에서 추가하고, 원본 양식은 앞으로 만들 프로젝트를 위해서만 고칩니다).
• 다음 시간: template 과 달리 '설치'해서 쓰는 공용 기능 묶음 core(공통 기능) 를 봅니다.