프로젝트 아키텍처

이 파일은 템플릿이다. <...> 부분을 이 프로젝트의 실제 내용으로 채워야 동작한다. harness-installer 스킬로 설치했다면 초안이 자동으로 채워져 있다 — 초안을 검토해 확정하라. 이후 아키텍처가 바뀌면 harness-evolve 스킬이 이 파일을 갱신한다.

채울 때 지켜야 할 규칙

이 규칙들은 실제 운영에서 드리프트(문서와 코드의 어긋남)를 겪고 얻은 것이다.

• 낡는 정보를 쓰지 않는다. 파일 개수, 패치 버전, 항목 개수("환경 7개") 같은 값은 코드가 조금만 바뀌어도 틀린 문서가 된다. 개수를 세지 말고 원본이 어디인지 적어라 (예: "환경 목록의 원본은 config/*.yml").
• 원본을 명시한다. 여기 적은 값과 코드가 다르면 코드가 이긴다. 어느 파일이 원본인지 적어두면 다음 사람이 갱신 대신 확인만 하면 된다.
• 코드만 봐서는 오해하는 것을 우선 적는다. 여기의 가치는 디렉터리 목록이 아니라 읽어도 모르는 정책이다 — 전역 에러 응답 규약, ORM의 사용 범위 제한, 캐시 무효화 책임 등.
• 왜(Why)를 병기한다. 규칙만 적으면 엣지 케이스에서 잘못 적용된다.

프로젝트 개요

<이 서비스가 무엇을 하는가. 2~3문장. 도메인 용어를 여기서 한 번 정의한다.>

기술 스택

정확한 버전은 <package.json / build.gradle / pyproject.toml …>이 원본이다. 아래는 메이저 버전만 적는다 — 패치 버전은 업그레이드 시 조용히 낡는다.

환경 구분

<환경 승격 체인. 예: local → dev → stage → production>

• 설정 파일: <경로> — 환경 목록의 원본은 이 파일들이다
• 환경 결정 방식: <환경 변수명과 기본값>
• 환경별로 다른 인프라 구성이 있으면 여기에 <예: production만 HA 구성, credential 주입 방식>

디렉터리 구조

<트리. 각 디렉터리 옆에 한 줄 역할 설명. 개수·파일명 나열은 하지 않는다.>

레이어 아키텍처 (요청 흐름)

<요청이 들어와서 저장소에 닿기까지의 경로를 한 줄로>

레이어 규칙 중 위반하기 쉬운 것을 명시한다 (예: "Controller에 비즈니스 로직 금지", "Model에서 외부 API 호출 금지", "Lib는 req/res를 직접 참조하지 않는다").

인증 / 인가

에러 처리 패턴

• 커스텀 에러 클래스: <기반 클래스와 정의 파일>
• 응답 규약: <상태 코드와 바디 형태. 표준과 다른 규약이라면 반드시 여기에 — 이걸 모르는 리뷰어는 규약을 지킨 코드를 결함으로 지적한다>
• 예외 캡처: <모니터링 도구>

캐싱 전략

• 캐시 대상과 저장소: <>
• 키 프리픽스와 TTL: <정의된 파일 위치를 적는다. 값을 복사하면 낡는다>
• 무효화 방식: <cache-aside인지, 누가 무효화 책임을 지는지>
• TTL이 없는 캐시가 있다면 반드시 표시한다 — 무효화를 빠뜨리면 낡은 데이터가 무기한 서빙된다.

비동기 / 알림 / 배치

<이벤트 발행 방식, 스케줄러, 큐, 알림 채널. 없으면 "없음"으로 명시한다.>