---
name: architecture-generator
description: 요구·기술 결정·현재 코드를 연결해 docs/ARCHITECTURE/overview.md에 구성·경계·핵심 흐름·필요한 데이터와 API 계약을 설계하거나 갱신한다.
---

# 구조와 흐름

## 목적과 입력

`docs/PRD.md`·`docs/TRD.md`의 요구·기술·합의와 관련 코드·기존 설계를 읽는다.
현재 구현과 앞으로 바꿀 구조를 구분한다. 입력이 없으면 요청 범위에 필요한 최소 결정을 먼저 정리한다.
문서화만 요청된 기존 코드는 현행 근거를 기록하며 새 제품 기획이나 구현을 강제하지 않는다.
이미 정해진 선택은 재질문하지 않고 기술·설계 변경 재량은 PRD 합의를 따른다.

## 최소 산출물

`docs/ARCHITECTURE/overview.md`에 아래 내용을 간결하게 남긴다.

- 구성 요소·책임·경계와 의존 방향
- 핵심 사용자/처리 흐름, 중요한 실패와 권한 검사 지점
- 구현에 필요한 데이터 관계·상태 전이·API 요청/응답 등 계약
- 관련 FR/NFR/TD 또는 코드 근거와 구조를 확인할 관찰 기준
- 실제 충돌·잠정 설계·미결과 영향, 분리한 문서가 있으면 링크

작은 프로젝트는 overview 하나면 충분하다. 분리할 내용이 있을 때만 같은 폴더의
`frontend.md`·`backend.md`·`database.md`·`auth.md`·`security.md` 등에 나눈다.
그림이 관계를 더 잘 설명하면 Mermaid를 쓴다. 빈 영역·반복 추적표·거대한 템플릿은 만들지 않는다.
요구와 TD는 관련 절에서 참조하고 같은 결정을 여러 문서에 복제하지 않는다.

화면 제품은 디자인 정본을 입력으로 읽고 승인 방향을 색·글자·간격 등 공통 토큰, 재사용 구성 요소, 화면 구성·주요 상태·반응형 규칙에 연결한다.
시각 세부 선택은 승인 범위 안에서 자율 결정하고 범위 밖 새 방향은 PRD의 미리보기·사용자 확정 단계로 연결한다.

## 설계와 충돌 처리

- PRD는 제공할 결과, TRD는 기술 선택, Architecture는 선택 안의 책임·계약을 정한다.
  구현 순서·태스크 분할은 Plan, 실제 검사 수단은 Harness에서 정한다.
  제품 Loop의 네 게이트·비상속 별도 세션 task_validation에서 관찰할 경계와 실행/접속 전제를 연결한다.
- 핵심 흐름을 입력부터 응답/저장까지 따라가며 계약 누락·모순·NFR 실현 가능성을 확인한다.
- 구조 조정으로 요구를 모두 만족하면 스스로 해결한다. 앞 문서를 바꿔야 하는 실제 충돌만 `CF-xxx`로 기록한다.
  관련 요구/TD·증거·영향·조치·남은 차단을 적는다. 충돌이 없으면 검토 대상과 0건임을 짧게 밝힌다.
- 위임된 기술·설계 선택은 자율 결정하고 가장 앞의 영향 문서(IDEA 포함)부터 해당 부분만 맞추며 근거·현재 기준 포인터를 남긴다.
  범위·수용 기준·사용자 제약을 바꾸는 변경은 스스로 정하지 않고 결정 전까지 기존 기준을 유지하며 사용자 결정으로 묻는다. 앞 문서 반영은 단계 전환이 아니다.
  사용자가 지시한 새 요구도 PRD부터 반영하며 같은 내용을 다시 승인받지 않는다.
- 위임되지 않은 범위·예산·데이터 권한은 실행 전에 해소한다. 기준을 낮춰 충돌을 숨기지 않는다.
- 잠정 TD/OQ/CF 위의 구조는 잠정임과 바뀔 지점을 명시한다. 근거 없는 확정 설계를 만들지 않는다.
  실험이 필요한 주장은 관찰·판정 기준을 남기고 허용 범위에서 확인한다.
- Loop 이후 새 결정 없이는 못 하는 영역은 차단하고 독립 작업을 계속한다.
  진행 불가이면 증거·미완료 범위·재개 조건을 남기며 질문 대기로 끝내지 않는다.

## 갱신과 호환

기존 문서는 영향 절만 갱신한다. `파일명 §절번호` 참조·CF/OQ/요구/TD ID·사용자 수정·해소 이력을 보존한다.
새 절/ID는 끝에 붙이고 사라진 절은 대체/폐기를 연결한다. 새 OQ는 프로젝트 전체 번호와 충돌을 확인한다.
기능 추가·리팩토링의 `## 추가 N`·`## 리팩토링 N` 후미 절 요청을 보존한다.
변경 이력과 문서 링크를 맞추고 영향 있는 계획·하네스·루프만 갱신한다.
실행 중 상태는 현재 실행 주체가 안전한 경계에서 반영한다. 루트 지침은 필요한 포인터만 보완한다.

## 완료 증거와 연결

작업 시작·중요 결정·종료 때 설계나 기존 STATE/LOG에 현재 단계·확정/미결·다음 행동과 근거를 증분 저장한다.
원 대화 없이 계약·잠정 영역을 이어받게 하되 작은 설계 요청에 전체 계획 체계를 강제하지 않는다.
사용자 명시 기본값 변경·자식 실행 금지를 우선하고 달라진 보장·미검증을 후속 Plan/Harness/Loop에 전달한다.

핵심 요구와 중요한 NFR에 책임/계약이 있고 실제 흐름을 끝까지 설명할 수 있는지 확인한다.
문서 링크·근거·계약 간 일치, 실패 경로와 잠정/차단 표시를 점검한다. 미실행 검증은 완료로 쓰지 않는다.
변경 문서·해소/잔여 충돌·미검증 범위를 보고한다. 설계만 요청되면 여기서 끝내고 다음 스킬을 제안한다.
다음 단계는 `plan-generator`다. 단계를 마치면 결과(요약·주요 결정·가정·남은 결정)를 보고하고 다음 스킬로 이어 진행할지 사용자에게 확인한다. 수정 요청은 반영해 다시 보고한다. Loop 실행 전까지 모든 단계에 적용하며, 사용자가 자기 말로 단계별 확인 생략을 지시했을 때만 확인 없이 이어 간다. '만들어줘'·'끝까지'나 사전 권한·예산 합의만으로는 생략하지 않고, 에이전트는 확인 생략이나 자동 진행을 먼저 권하거나 추천하거나 생략 방법을 안내하지 않으며, 그렇게 받은 선택도 근거가 아니다. 진행이 확인되면 실행을 사용자에게 떠넘기지 않는다.

## 환경 참고

도구 차이가 필요할 때만 [Claude Code](references/claude-code.md) 또는 [Codex](references/codex.md)를 읽는다.