- 항상 사용자를 '대장'이라고 호칭한다.
- 모든 설명과 산출물은 한글로 작성한다.
- 작업이 끝나면 대장이 바로 복사해 커밋할 수 있도록, 한 줄짜리 한글 커밋 문장만 남기고(라벨 없이 메시지만 제시), 직접 커밋까지 진행한다.
- 본 문서 상단의 글로벌 규칙은 모든 서브 에이전트가 반드시 따른다.
- 서브 에이전트 섹션에는 글로벌 규칙 위에 얹는 역할별 추가 책임(델타)만 적는다.
- 호칭·언어: 저를 “대장”이라 부르고, 모든 대화는 한글로.
- 작업 방식: 플랜모드로 계획을 꼼꼼하게 세운 다음 그 계획에 맞게 todo 목록을 만들고, 하나씩 체계적으로 자동 실행.
rm/mv로 삭제·이동은 사전 승인 필수, 그 외 bash/편집은 자동 처리 가능.- 내가 요청한 범위를 훨씬 벗어나는 부분은 수정하거나 삭제하지 말고, 요청한 내용에 충실하게 집중해서 작업할 것.
- 마이그레이션이 필요한 경우 마이그레이션 관련 명령어는 직접 자동으로 진행해도 된다.
- 명령: 장고 명령은 항상
uv run사용. 개발 서버는 대장이 수동 관리(재시작 필요 시 알림). - 템플릿 가이드: 템플릿명과 동일한
css/js를static에 생성, 토스트 미사용, 다크모드 대응. - 문서화: 중요한 개선사항은
README.md에 체계적으로 업데이트. - 테스트는 내가 수동으로 할 것이니 직접 자동으로 하지 말고, 테스트하는 방법만 제시할 것
- 큰 규모의 작업이 요청되면 루트의
todo.md파일에 현재 진행 중인 작업을 할일 목록으로 기록하고, 각 항목을 순차적으로 처리한다. - 작업을 시작하기 전에 최신
todo.md를 확인하고 필요한 경우 업데이트한다. - 작업 후에는 간단한 커밋 메시지를 정리해서 알려주어야 한다. 바로 복사해서 붙여 넣을 수 있도록 한글로만 맨 끝에 별도 표시 없이 커밋 메시지 만들어줘라.예들 들어, "커밋 메시지 제안: " 등과 같이 앞 부분은 없애고 바로 커밋 메시지를 한글로 알려줘라. 이후 자동으로 해당 커밋 메시지를 적용한 커밋을 실행한다.
- ✅ 커밋 메시지를 전달했다면 별도 지시가 없어도 동일한 메시지로 즉시
git commit을 완료해야 한다. (커밋 메시지 통보 → 자동 커밋 순서 준수)
- ✅ 커밋 메시지를 전달했다면 별도 지시가 없어도 동일한 메시지로 즉시
- 템플릿을 만들면 템플릿에 사용하는 js, css 파일을 템플릿 이름과 동일한 파일로 만들어 static 폴더에 저장
- css 패키지는 tailwind 사용. 기본 글꼴 크기는 text-sm 사용
- 토스트 메시지는 사용하지 말 것
- 반드시 다크모드 대응할 것
| 경로 | 설명 |
|---|---|
satoshop/ |
Django 프로젝트 설정, 전역 URL, 미들웨어, WSGI/ASGI 엔트리포인트가 위치합니다. |
manage.py |
Django 관리 명령 실행 진입점입니다. |
accounts/ |
사용자 계정/인증 뷰, LNURL 연동 로직, 템플릿이 포함된 앱입니다. |
products/ |
상품, 옵션, 카테고리 모델과 관련 서비스/템플릿을 담습니다. |
stores/ |
스토어(셀러) 관리 앱으로, 스토어 모델/폼/템플릿과 관리자 뷰를 제공합니다. |
orders/ |
장바구니, 주문, 인보이스 모델과 결제 후 처리 뷰·서비스가 모여 있습니다. |
ln_payment/ |
Blink 기반 라이트닝 결제 API 연동 서비스와 뷰를 제공합니다. |
myshop/ |
공용 페이지, 캐시 유틸리티, 템플릿 태그 등 사이트 전반 기능을 담은 코어 앱입니다. |
reviews/, menu/, meetup/, game/ |
각각 후기, 메뉴, 오프라인 모임, 미니 게임 등 부가 기능 앱입니다. |
templates/, static/, staticfiles/ |
글로벌 템플릿과 정적 자산이 위치합니다 (collectstatic 결과는 staticfiles/). |
scripts/ |
배포/운영 자동화 스크립트와 크론 작업 도구가 있습니다. |
requirements.txt, pyproject.toml, uv.lock |
파이썬 의존성과 개발 도구 구성이 정의됩니다. |
- 의존성 설치:
uv sync - DB 기동(개발):
docker compose up -d postgres - 마이그레이션:
uv run python manage.py migrate - 개발 서버:
uv run python manage.py runserver(대장이 수동 관리하므로 재시작 필요 시에만 알려주세요) - 슈퍼유저:
uv run python manage.py createsuperuser - 테스트(전체/앱):
uv run python manage.py test/uv run python manage.py test pages - 배포 스크립트:
./build.sh(Render에서 호출)
- Python: PEP 8, 4칸 들여쓰기. 클래스
PascalCase, 함수/변수snake_case. - Django: 모델 단수형, 앱별 템플릿은 각 앱 또는
templates/활용. - 프런트엔드: ES6+. 섹션 폴더는
snake_case(또는kebab-case) 예:hero_section/. - 템플릿에 정적파일을 넣지 말고 각 앱
static/{css,js}/에 배치. 다크모드 대응 필수.
- 비밀정보 커밋 금지.
local.env사용(website/settings.py에서 로드). - 주요 환경:
SECRET_KEY,DEBUG,DATABASE_URL(또는 개별 DB 변수),ADMIN_*(빌드 시 사용). - 운영 배포 시
ALLOWED_HOSTS를 정확히 설정.
- 지시한 내역을 아래와 같은 형식으로 변경 이력을 기록한다.
- 폴더 : 루트/change-log/ 내 YYYY-MM 하위 폴더를 만들고, 해당 월의 변경 이력 파일을 그 폴더에 저장한다.
- 단위: “작업(이슈/PR/스펙항목)” 단위 1파일
- 파일명: YYYY-MM-DD__.md 예) 2025-11-08_checkout-addrs_normalize.md
- scope는 앱/도메인 레벨(예: auth, checkout, analytics).
- “짧은 제목”은 나중에 릴리스 노트에 그대로 쓰일 만큼 간결하게.
- 요구사항→기능→엔드포인트를 HTMX 부분 갱신 중심으로 설계하고, 기본은 Tailwind를 사용하되 기존 expert 영역에서만 Bulma 기본 클래스를 유지·확장한다.
- 도메인/서비스/프레젠테이션 레이어를 분리한 구조를 강제하며, View 단 비즈니스 로직·트랜잭션 제어는 금지한다.
- 스토리지(R2)와 정적 자산은 중앙 유틸(common.r2, 해시 캐시 무효화)을 사용하도록 아키텍처를 잡는다.
- 국제화는 서버/템플릿/HTMX 조각 모두 동일하게 적용되도록 설계하며, 새 문자열 추가 시 메시지 컴파일 플로우를 포함한다.
- 새 View 추가 시
/docs/api_reference.md갱신을 설계 산출물 범위에 포함한다. - 금지: 코드 출력 금지(설계 산출물만), 기능/엔드포인트/DB 초안만 제시.
- 서비스 계층/폼/시리얼라이저로 로직을 분리하고, View에서는 직업 로직·트랜잭션 제어를 하지 않는다.
- HTMX 대응을 위해 조각 템플릿 반환을 기본값으로 하고, URL 네이밍은
app:view_name패턴을 따른다. - 스토리지 작업은
common.r2.R2Client유틸만 사용하고, 정적 자산은 해시 기반 캐싱을 전제로 빌드한다. - 국제화 문자열은
_,ngettext_lazy, 템플릿{% trans %}/{% blocktrans %}를 사용해 서버에서 번역 후 내려보낸다. - 테스트는 DB 연동 없는 모킹/단위 테스트로 작성하며, View/Service/Model별 최소 1개 이상과 커버리지 70% 이상을 유지한다.
- 금지: UI 언급 금지(HTMX/템플릿 구조 설명은 프런트 범위), 엔드포인트 상세/ORM/에러 매핑만 제시.
- HTMX 기반 상호작용을 기본으로 하고, 기본 스타일은 Tailwind로 구성하며 expert 영역 한정으로 Bulma 기본 클래스를 유지·보완한다(충돌 시 Tailwind 우선 적용 후 Bulma 보정). 커스텀 CSS/JS는 앱별
static/js|css로 최소화한다. - 온디멘드 카테고리/정렬/검색 컨트롤은 규정된 크기(
font-size: 0.85rem,min-height: 3.25rem,padding: 0 1rem)를 지키고, 좌측 필터·우측 검색 2열 레이아웃을 유지한다. - 알림은 공통 토스트 컴포넌트 하나로 통일하고, 서버
messages응답도 동일 토스트로 변환한다. - 서비스 워커와 manifest를 유지해 PWA 캐시를 관리하고, 이미지·첨부는 R2 업로드 정책(WebP 변환, 용량·개수 제한)을 준수한다.
- 템플릿 국제화 태그를 사용해 HTMX 부분 갱신 시에도 번역된 문자열을 렌더링한다.
- 금지: 서버 내부 로직·DB 언급 금지, 화면맵/페이지 구조/상태·검증 규칙/API 호출 타이밍만 제시.
- 테스트 우선순위: HTMX 부분 갱신 경로(조각 응답) → 서비스/폼/시리얼라이저 단위 → 퍼블릭 API/페이지 happy path.
- DB 연동 테스트는 금지하고, 모킹/단위 테스트로 대체하며 커버리지 70% 이상을 강제한다.
- View/Service/Model별 최소 1개 테스트를 유지하고, 국제화 문자열이 제대로 렌더되는지 템플릿 단위 검증을 포함한다.
- 릴리즈 전 체크리스트: 토스트 알림 동작, 필터/검색 실시간 반응, R2 업/다운/삭제 유틸 호출 경로, PWA 캐시 영향 여부.
- 금지: 코드 생성 금지, 수용 기준/시나리오/체크리스트만 제시.