harness_loop_full_koreanSAFE

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

flowchart TD
A["PRD → TRD → Architecture → Master Plan"]

A --> B["Phase"]
B --> C["Task"]
C --> D["Implement"]
D --> E{"Verify"}

E -->|FAIL| F["Fix"]
F --> E

E -->|PASS| G{"More Tasks?"}

G -->|YES| C
G -->|NO| H["Phase Complete"]

H --> I{"Next Phase?"}

I -->|YES| B
I -->|NO| J["Project Complete"]

classDef process fill:#e8f4ff,stroke:#1976d2,stroke-width:1.5px,color:#0d47a1;
classDef decision fill:#fff8e1,stroke:#f9a825,stroke-width:1.5px,color:#5d4037;
classDef complete fill:#e8f5e9,stroke:#43a047,stroke-width:1.5px,color:#1b5e20;

class A,B,C,D,F process;
class E,G,I decision;
class H,J complete;

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: architecture-generator
description: docs/PRD.md와 docs/TRD.md를 읽고 프로젝트 전체 아키텍처를 docs/ARCHITECTURE/ 아래에 작성한다. overview.md에 시스템 구성·경계·핵심 흐름을 담고, frontend.md·backend.md·database.md·auth.md·security.md 등 영역별 문서로 나눠 기록하며, 무엇보다 PRD·TRD와 충돌하는 설계가 있는지 검토해 봉합하지 않고 드러낸다. 사용자가 "아키텍처 설계해줘", "구조 잡아줘", "설계 문서 써줘", "테이블 설계해줘", "API 설계해줘", "폴더 구조 어떻게 나눌지 정해줘"라고 하거나, TRD 검토를 마치고 다음 단계로 넘어갈 때 반드시 이 스킬을 사용한다. 요구사항과 기술 스택은 정해졌는데 구조가 문서로 없는 상태에서 개발 계획을 세우거나 코드를 짜기 시작하려 할 때도 이 스킬로 먼저 설계를 고정한다.
---

# 아키텍처 작성 (Layer 2)

## 이 스킬의 목적

아키텍처는 **"고른 기술 안에서 어떤 모양으로 만들 것인가"**에 대한 합의문이다.
PRD가 사용자에게 한 약속이고 TRD가 그 약속을 지키려고 고른 수단이라면, 아키텍처는 그 수단을 실제 구조로 배치한 것이다.

여기서 정한 구조가 뒤에서 이렇게 흘러간다.

```
아키텍처의 설계 단위 (database.md §3.2 인보이스 번호 채번)
   → 태스크의 Files·Architecture 항목이 이걸 가리킨다      (Layer 3)
   → 품질 게이트가 검증할 대상이 여기서 나온다              (Layer 4)
   → 루프의 한 태스크가 "무엇을 건드려도 되는가"의 경계가 된다 (Layer 5)
```

그래서 이 문서의 품질은 "구조가 세련됐는가"가 아니라 두 가지로 판정된다.

1. **각 설계가 어느 요구사항·기술 결정 때문인지 적혀 있는가**
2. **PRD·TRD와 어긋나는 지점을 조용히 봉합하지 않고 드러냈는가**

두 번째가 이 레이어의 핵심이다. 요구사항과 기술 결정이 처음 **동시에** 한 사람 앞에 놓이는 곳이 여기다.
PRD를 쓸 때는 기술이 없었고 TRD를 쓸 때는 구조가 없었으므로, 둘이 못 만나는 지점은 **아키텍처를 그려 봐야 비로소 보인다.**
그리고 그 지점을 여기서 못 보면, 다음에 보이는 곳은 Layer 5에서 태스크가 세 번 실패하고 멈추는 순간이다.

### 여기서 하는 일과 하지 않는 일

| 하지 않는 것 | 어디서 하는가 |
|---|---|
| 요구사항을 새로 만들거나 우선순위를 바꾸는 것 | PRD (`prd-generator`) — 사용자가 정하면 이 세션이 PRD 부터 고치고 이어 간다(8단계 "앞 문서 반영") |
| 기술을 새로 고르거나 바꾸는 것 (라이브러리 교체 포함) | TRD (`trd-generator`) — 위와 같다 |
| 개발 순서, 태스크 분할, phase 구성, 일정 | Layer 3 마스터 플랜 (`plan-generator`) |
| 품질 게이트 4단계 구성, E2E가 덮을 흐름 목록, task validation 절차 | Layer 4 하네스 (`harness-setup`) |
| 실제 코드, 마이그레이션 파일, 설정 파일 작성 | Layer 5 개발 루프 |

**아키텍처는 요구사항도 기술도 만들지 않는다.** 설계하다 보면 둘 다 만들고 싶어진다 —
"여기 관리자 화면이 있어야겠는데"(요구사항), "이건 큐가 있어야 되겠는데"(기술).
그렇게 문서에 슬쩍 들어간 것은 추적표에 근거가 없고, PRD·TRD 어느 쪽에서도 검토받지 않은 채 Layer 3에서 태스크가 된다.
**둘 다 충돌로 올려 사용자가 정하게 하고, 정해지면 앞 문서부터 고친 뒤 설계한다.** 2단계와 8단계 "앞 문서 반영"이 그 방법이다. 아키텍처가 스스로 넣는 것은 여전히 없다 — 바뀌는 것은 정해진 뒤 누가 문서를 고치느냐다.

### TRD와 아키텍처의 경계

TRD가 이미 정해 둔 기준이 있다 — **후보 중 하나를 고르는가, 고른 것 안에서 모양을 정하는가?**

| TRD (고른다) | 아키텍처 (모양을 정한다) |
|---|---|
| 관계형 DB를 쓴다. 후보 중 X를 고른다 | `invoices` 테이블에 어떤 컬럼과 인덱스를 두는가 |
| HTTP + JSON, 오류 응답은 한 형식으로 통일한다 | 그 형식이 정확히 어떤 모양이고, 어떤 경로가 있는가 |
| 세션 기반 인증, 역할은 소유자 단일 | 소유권 검사를 어느 계층에서 강제하는가 |
| 브라우저 자동화 도구로 X를 쓴다 | (아키텍처 밖 — Layer 4) |

**TRD의 결정을 다시 검토하지 않는다.** "이 DB보다 저게 나은데"는 여기서 할 말이 아니다.
다만 **그 결정으로는 요구사항을 만족시킬 수 없다는 것이 설계 중에 드러나면** 그건 취향이 아니라 충돌이므로 반드시 올린다.

---

## 1단계. 입력 확보와 사전 점검

**`docs/ARCHITECTURE/` 가 이미 있으면 작성(1~7단계)을 다시 돌지 않는다** — 남은 충돌·미결을 푸는 것이면 8단계, 설계를 바꾸는 것이면 9단계(부분 갱신)만 한다. 8단계로 풀었는데 `plan_setup/` 이 이미 있으면, 끝에 9단계의 버전·`변경 이력` 한 줄·뒤 문서 맞추기를 한다 — 버전이 그대로면 플랜이 알아채지 못한다.

`docs/PRD.md` 와 `docs/TRD.md` 를 **둘 다 전문으로 읽는다.** 요약본으로 대체하지 않는다.
충돌 검토는 두 문서의 세부 문장이 서로 안 맞는 것을 잡는 일이라, 요약하는 순간 잡아야 할 것이 사라진다.

**둘 중 하나라도 없으면 아키텍처를 쓰지 않는다.**

- PRD가 없으면 → 무엇을 만족시켜야 하는지 모르는 채로 구조를 그리게 된다. `prd-generator` 를 먼저 제안한다
- TRD가 없으면 → 기술 선택이 설계에 섞여 들어간다. `trd-generator` 를 먼저 제안한다

사용자가 "그냥 있는 걸로 진행해달라"고 하면, 없는 문서 대신 무엇을 근거로 삼았는지를 overview.md 1절에 명시하고 진행한다.
근거가 사용자의 구두 설명이면 그 문장을 그대로 인용해 둔다. 나중에 이 설계가 왜 이런지 물을 사람에게 남길 수 있는 것이 그것뿐이다.

읽으면서 다음 네 가지를 먼저 추린다.

| 추릴 것 | 어디서 | 왜 |
|---|---|---|
| **차단 미결** | PRD 8절 · TRD 12절 | 되돌리기 비용이 큰 결정(저장소·인증 모델·배포 형태)에 걸린 미결이 남아 있으면 그 위의 설계는 통째로 재작업 후보다 |
| **잠정 결정** | TRD 각 TD의 확정도 | `잠정`·`스파이크 필요` 인 결정 위에는 **갈아 끼울 수 있는 모양**으로 설계한다 |
| **NFR 전부** | PRD 5절 · TRD 10절 | NFR은 구조를 직접 결정한다. 성능·보안·보존 기간은 기능보다 먼저 구조를 정한다 |
| **P0 요구사항** | PRD 9절 추적표 | P0가 흐르는 경로가 아키텍처의 뼈대다 |

**차단 미결이 남아 있으면 설계를 시작하기 전에 사용자에게 알린다.** 두 가지 중 하나를 고르게 한다.

1. 이 자리에서 그 미결을 사용자와 풀고, 답을 앞 문서에 반영(8단계의 "앞 문서 반영")한 뒤 설계를 이어 간다 (권장)
2. 기본값으로 진행하되, 영향받는 영역을 **'잠정 설계'**로 표시하고 뒤집혔을 때 무엇을 다시 그려야 하는지 명시한다

임의로 2번을 고르지 않는다. 다시 그리는 비용을 치르는 건 사용자다.

## 2단계. 충돌 검토 — 이 스킬의 핵심

원본 사양이 이 레이어에 명시적으로 요구한 것이 **"PRD.md·TRD.md와 충돌하는 설계가 있는지 검토한다"**이다.
설계를 다 그린 뒤 검토하는 것이 아니라, **그리는 동안 계속 하는 일**로 다룬다. 충돌은 대개 구체적인 구조를 그려 볼 때만 드러나기 때문이다.

### 무엇이 충돌인가

네 종류가 있고, 각각 다른 곳으로 돌려보낸다.

| 종류 | 어떤 모양으로 나타나는가 | 어디로 돌려보내는가 |
|---|---|---|
| **요구사항 ↔ 기술 결정** | 어떤 구조를 그려도 그 TD로는 그 FR·NFR을 만족시킬 수 없다 | TRD (결정 교체) 또는 PRD (요구사항 조정) — 사용자가 고른다 |
| **요구사항 ↔ 요구사항** | 두 FR·NFR을 동시에 만족시키는 구조가 없다 | PRD |
| **기술 결정 ↔ 기술 결정** | 두 TD가 같은 지점에서 서로 다른 것을 요구한다 | TRD |
| **설계 유발** | 설계가 앞 문서에 없는 요구사항·기술을 요구하게 된다 | 그 요구사항은 PRD, 그 기술은 TRD |
| **사용자 요청 ↔ 앞 문서** | 지금 이 작업을 시키면서 사용자가 말로 요구한 것이 PRD·TRD에 없거나 그것과 어긋난다 | 요구사항이면 PRD, 기술이면 TRD |

**다섯 번째가 실무에서 가장 자주 나온다.** "이왕 하는 김에 저것도 넣어줘", "그건 바꿔도 돼" 같은 말은
설계를 시키는 자리에서 자연스럽게 나오지만, **말로 한 요청은 아직 어느 문서에도 없다.**
그대로 넣으면 검토받지 않은 요구사항·기술이 아키텍처를 통해 뒷문으로 들어오고, Layer 3은 그것을 PRD·TRD와 같은 무게로 읽는다.

그렇다고 무시하지도 않는다. **사용자가 요청한 것을 조용히 빼면 사용자는 자기가 말한 것이 빠진 줄 모른 채 다음 레이어로 넘어간다.**
충돌로 올려 "지금 반영하지 않았고, 넣으려면 어느 문서를 고쳐야 하는가"를 보이는 것이 양쪽을 다 피하는 유일한 길이다(사용자가 그 CF 에 답하면 8단계 "앞 문서 반영"으로 PRD·TRD 부터 고친다).
사용자의 원래 문장을 그대로 인용해 둔다 — 나중에 "내가 그런 말 했나"를 판정할 근거가 그것뿐이다.

네 번째 종류(설계 유발)도 자주 놓친다. **"이걸 만들려면 X가 필요한데 어디에도 없네"** 는
설계자가 조용히 X를 넣어 해결할 수 있기 때문이다. 그렇게 들어간 X는 아무도 검토하지 않았고, 예산에도 일정에도 없다.

### 충돌은 봉합하지 않고 드러낸다

가장 흔하고 비싼 실수가 **"설계로 어떻게든 맞추는 것"**이다. 그럴듯한 구조를 하나 만들어 내면 문서상으로는 충돌이 사라진다.
사라진 것은 충돌이 아니라 **충돌이 있었다는 사실**이고, 남은 것은 복잡한 구조와 아무도 이유를 모르는 우회 경로다.

그래서 이렇게 처리한다.

- 충돌마다 **CF-001** 형태의 ID를 붙이고 overview.md의 충돌 검토 결과 표에 남긴다
- 지금 진행하기 위해 **잠정 설계**를 세우는 것은 괜찮다. 다만 그것이 잠정임을 해당 문서에 적고 CF를 가리킨다
- **해소는 사용자의 결정이다.** 어느 쪽을 굽힐지(요구사항인가 기술인가)는 비용과 목표를 아는 사람이 정한다

### 충돌 하나의 형식

```markdown
| CF-002 | NFR-002(PDF 10초) ↔ TD-017(서버 헤드리스 브라우저 렌더) | 요구사항↔기술 결정 | 조항 30개 문서에서 렌더 시간이 예산을 넘길 가능성이 높고, 어떤 구조로도 렌더 자체를 빠르게 만들 수 없다 | 1 TD-017을 문서 생성 라이브러리로 교체 2 NFR-002를 20초로 조정 3 비동기 생성으로 바꾸고 FR-008의 수용 기준을 다시 쓴다 | 3으로 잠정 설계. backend.md §3.4에 표시 | TRD 또는 PRD | 아니오 |
```

열은 `ID | 무엇과 무엇이 | 종류 | 왜 충돌인가 | 선택지 | 지금 취한 조치 | 돌려보낼 곳 | P0 뼈대`.

**마지막 열이 무엇을 위한 것인지**가 중요하다. 이 충돌이 **P0 흐름의 뼈대**(개체와 관계, 인증 모델, 요청 처리 경로) 위에 있으면 `예`,
아니면 `아니오`를 적는다. 8단계의 멈춤 조건이 이 열로 판정되고, Layer 3은 이 열이 `예`인 미해소 충돌에 걸린 태스크를 `blocked` 로 만든다.
표시가 없으면 다음 레이어는 다섯 건이 다 같은 무게로 보이고, 정작 뼈대를 흔드는 하나가 묻힌다.

**선택지를 반드시 셋 이하로 적는다.** 사용자가 판단할 수 있어야 충돌을 올린 의미가 있다.
"충돌이 있습니다"만 적으면 사

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (3)

$r = Invoke-WebRequest -Uri "http://127.0.0.1:$($C.MailWebPort)/api/v1/info" -UseBasicParsing -TimeoutSec 3

const m = text.match(/^?---\r?\n([\s\S]*?)\r?\n---/);

<#

Gates applied: no_behavioural_pass.