# 통합 범용 서비스 공동개발·인증·PWA·공유저장·저숙련 AI 무해석 5단계 원샷 개발 마스터 v3.4

정본일: `2026-09-09`

## 사용 목적

현재 프로젝트의 기존 기획서·제품요구서·로드맵·개발계획서를 전수 통합하고, 일반 공동개발, GitHub 권한 검증, Google 로그인·무료 가입·내 계정, QR·PWA, 결제 제외 프리미엄 기능, 공유 저장·동시편집·오프라인 충돌 처리를 보존하면서, 공개 운영 1년 이상인 비교 가능한 무료 상용 서비스의 모바일·PC 상세 기준을 조사한다. 기존 계획과 새 격차를 하나의 초세밀 제품기획과 **저숙련 AI가 추가 질문·재기획·추측 없이 그대로 실행할 수 있는 5단계 개발계획**으로 합친 뒤 실제 구현·검사·승인된 기존 공개판 반영까지 이어 간다. 모든 모드에는 최소 10배의 유효 분석·설계·구현·시험 계약과 분량 부풀리기 방지 관문을 적용하여 후속 AI가 재해석하지 않아도 되는 완결 실행 묶음을 만든다.

이 문서 전체를 개발 대상 프로젝트의 AI 작업창에 한 번 붙여 넣는다. **붙여 넣는 행위 자체가 분석·계획·구현 시작 명령이다.** 서비스명·URL·모드·기술스택을 사용자가 다시 입력하기 전에 프로젝트 지침·파일·구성·공개 증거에서 자동 감지한다.

## 0A. 붙여넣기 즉시 실행·끝까지 진행 계약

`PASTE_AND_RUN=true`  
`AUTO_START_WITHOUT_CONFIRMATION=true`  
`LOW_SKILL_AI_FIVE_STAGE_BUILD=true`  
`FIVE_STAGE_EXECUTION_MODE=PLAN_THEN_IMPLEMENT`

1. 프롬프트 수신 즉시 프로젝트 지침, Git 상태, 기존 변경, 현재 실행·시험 명령, 기존 계획, 공개 URL을 읽고 실행 장부를 만든다. “시작할까요?”, “어떤 모드인가요?”, “프로젝트 정보를 주세요”라고 먼저 묻지 않는다.
2. 자동 감지 결과에 따라 가장 포괄적인 안전 모드를 고른다. 기획만 요청한 명백한 증거가 없고 개발 요청이면 5단계 계획을 만든 뒤 같은 실행에서 승인 범위의 `READY` 작업을 실제 구현한다.
3. 서로 배타적인 제품 결정이 결과를 크게 바꿀 때만 영향받는 작업을 `BLOCKED_BY_DECISION`으로 격리한다. 추천 기본값으로 진행 가능한 다른 작업은 중단하지 않는다.
4. 외부 로그인·OTP·결제·비밀 입력·제3자 승인·실기기 조작이 필요하면 사용자 행동을 한 묶음으로 작성하되, 그 전에 가능한 코드·문서·자동시험·미리보기 준비를 모두 끝낸다.
5. 채팅 길이 때문에 작업을 줄이지 않는다. 상태와 결과를 파일에 저장하고 다음 미완료 작업 ID부터 이어 간다.
6. 계획 파일만 만들고 종료하지 않는다. 현재 권한과 도구로 실행 가능한 `READY`, `IN_PROGRESS`, `QUALITY_FAIL` 작업이 0개가 될 때까지 계획→구현→검사→수정 순환을 계속한다.
7. 실제 완료 증거가 없는 작업은 완료로 표시하지 않는다. 계획됨, 코드 작성됨, 자동검사됨, 공개검증됨, 실기기검증됨을 구분한다.

## 0B. 3단계 기록을 5단계로 승계하는 최상위 규칙

이 v3.4에서는 활성 개발계획과 실행 대기열을 **정확히 5단계**로 작성한다. 아래 엔진에 남아 있는 “3단계” 문구는 통합 당시 원문 보존용 기록일 뿐 활성 출력 형식으로 사용하지 않는다. 기존 3단계 계획은 삭제하지 않고 다음처럼 의미를 보존해 재배치한다.

| 이전 단계 | 새 단계 배치 | 승계 원칙 |
|---|---|---|
| 이전 1단계 안전·핵심 기반 | 새 1단계와 2단계 | 조사·보존·환경은 1단계, 구조·공통 기반·핵심 무료 경로는 2단계 |
| 이전 2단계 성숙 비교군 중앙값 | 새 3단계 | 핵심 사용자 여정·필수 기능·자료 흐름 완성 |
| 이전 3단계 상위 사분위·차별화·내구성 | 새 4단계와 5단계 | 품질·차별화·운영 내구성은 4단계, 공개·전체검증·안정화·인수는 5단계 |

기존 `DEV-S1-###`~`DEV-S3-###` ID는 원문 추적용 별칭으로 보존하고, 활성 작업에는 `DEV-S1-###`~`DEV-S5-###` 중 하나를 새로 부여한다. `legacy-stage-id`와 `active-stage-id`를 추적표에 함께 기록한다.

## 0C. 저숙련 AI 무해석 5단계 개발계획

| 단계 | ID | 실제 목표 | 필수 결과 |
|---|---|---|---|
| 1단계 | `STAGE-1-BASELINE` | 프로젝트를 망가뜨리지 않고 현행·정본·사용자 자료·개발환경·위험을 확정 | 기준선, 백업, 실행법, 실패 재현, 전체 작업 지도 |
| 2단계 | `STAGE-2-FOUNDATION` | 기술 구조·데이터·권한·공통 UI·핵심 무료 경로의 안전한 기반 완성 | 계약·구조·공통부와 최소 수직 기능의 자동시험 통과 |
| 3단계 | `STAGE-3-CORE` | 모바일·PC 핵심 사용자 여정과 필수 기능을 끝에서 끝까지 완성 | 정상·빈·로딩·오류·복구 흐름과 자료 왕복 통과 |
| 4단계 | `STAGE-4-QUALITY` | 접근성·성능·보안·동시성·오프라인·다국어·운영·차별화 완성 | 분야별 품질 예산과 장애·복구·관측 시험 통과 |
| 5단계 | `STAGE-5-RELEASE` | 전체 재검사·데이터 이전·공개·실기기·안정화·인수인계 | 공개판 증거, 되돌리기 시험, 운영 문서, 잔여 차단표 |

단계는 작업량을 다섯 등분한 일정표가 아니다. 선행 의존성·위험·사용자 가치가 완성되는 순서다. 각 단계는 이전 단계의 종료 조건을 실제 증거로 통과해야 시작하며, 독립적인 준비 작업만 제한적으로 병렬 실행한다.

### 0C-1. 단계별 상세 문서 24개 절

각 단계의 `stage-0N/README.md`에는 다음 절을 같은 순서로 작성한다.

1. 초보자용 한 문장 목표
2. 사용자에게 보이는 완료 모습
3. 포함 범위
4. 제외 범위와 이유
5. 진입 조건
6. 이전 단계 입력
7. 요구사항·격차·결정 ID
8. 작업 목록과 실행 순서
9. 의존 관계
10. 병렬 가능 작업
11. 반드시 순차인 작업
12. 변경 파일·기호·구성
13. 데이터·API·UI 계약
14. 정상 상태
15. 빈·로딩·부분 성공 상태
16. 오류·거부·오프라인·복구 상태
17. 모바일·PC·접근성·다국어 조건
18. 보안·개인정보·권한 조건
19. 성능·용량·비용 예산
20. 자동시험
21. 수동·실기기·외부 서비스 시험
22. 중단 신호와 되돌리는 순서
23. 종료 조건과 완료 증거
24. 다음 단계 인계 체크리스트

### 0C-2. 작업당 232개 판정 칸

기존 작업카드 20필드×10개 상세 칸인 200개 판정 칸을 보존하고, 저숙련 AI 친절성·구체성·실행 안전을 위한 다음 32개 칸을 더해 **작업당 232개 판정 칸**을 채운다.

201. 쉬운 말 작업 설명
202. 실제 사용자 상황 예시
203. 변경 전 문제 재현 절차
204. 변경 후 성공 장면 예시
205. 선행 작업 ID와 받아야 할 산출물
206. 후속 작업 ID와 넘겨줄 산출물
207. 시작 전 보관할 파일·자료
208. 새 파일의 전체 경로와 책임
209. 수정 파일의 전체 경로와 찾을 기호
210. 건드리지 않을 파일·함수·자료
211. 따라야 할 기존 구현 패턴의 실제 위치
212. 추천 구현 방식과 이유
213. 허용 대안과 선택 조건
214. 금지 방식과 실패 증상
215. 입력 예시·경계값·잘못된 값
216. 정상 출력·빈 출력·오류 출력 예시
217. 함수·컴포넌트·API 입력·출력 계약
218. 데이터 필드별 형식·필수·기본값·검증
219. UI 상태별 문구·행동·초점
220. 역할별 허용·거부 예시
221. 최소 12개 번호 붙은 구현 미세 단계
222. 미세 단계당 한 파일·한 변화
223. 단계 직후 가장 작은 확인
224. 복사 실행 가능한 명령과 작업 폴더
225. 성공 출력에서 확인할 값
226. 실패 증상별 다음 확인 명령
227. 최소 12개 고유 시험의 준비·입력·기대값
228. 일부러 틀린 구현을 잡는 반대 시험
229. 기존 기능 유지 전체 재검사 범위
230. 파일·설정·자료를 되돌리는 정확한 순서
231. 완료 증거 경로와 판정 문장
232. 다음 AI용 5문장 인계문

값을 확인하지 못하면 추측하지 않는다. `DISCOVERY-###` 선행 작업을 만들고 확인할 파일·명령·예상 출력·확인 뒤 채울 칸까지 지정한다. “알아서”, “적절히”, “관련 파일”, “필요하면”, “보통 방식”, “충분히 검사”만으로 넘기는 작업카드는 `NOT_READY`다.

### 0C-3. 친절한 구현 절차 형식

모든 `READY` 작업은 다음 형식의 미세 단계를 최소 12개 제공한다. 실제로 더 나눌 수 없는 원자 작업은 반복하지 말고 원자성 근거를 남긴다.

```text
STEP-01 — 동사로 시작하는 한 가지 행동
- 왜 하는가:
- 작업 전 화면·파일 상태:
- 작업 폴더:
- 열 파일 전체 경로:
- 찾을 기호·문구:
- 변경 전 예시:
- 수행할 한 가지 변경:
- 변경 후 예시:
- 바꾸지 않을 부분:
- 바로 실행할 명령:
- 성공 출력:
- 실패 증상별 확인 순서:
- 흔한 실수:
- 틀렸는지 확인하는 법:
- 되돌리는 법:
- 저장할 증거:
- 안전한 중단점:
```

코드 예시는 실제 프로젝트 언어·도구·기호를 확인한 뒤 작성하며, 복사 위치·필요 import·호출부·오류 처리·형식 규칙을 함께 제시한다. `...`, “나머지는 동일”, 의사코드만으로 핵심 구현을 생략하지 않는다. 전체 코드를 제시하는 것이 더 안전하면 완전한 작은 파일을 제공하고, 기존 파일 수정이면 변경 범위를 좁혀 설명한다.

### 0C-4. 작업·시험·복구 완결 조건

일반 작업은 최소 12개의 고유 시험, 인증·권한·결제·삭제·이전·공개·동시편집처럼 위험한 작업은 최소 24개의 고유 시험을 작성하고 가능한 범위에서 실제 실행한다. 각 시험은 ID, 선행조건, 시험자료, 실행 절차, 예상 결과, 실패 판정, 정리, 증거 경로를 가진다.

각 단계는 다음이 모두 참일 때만 완료한다.

- 단계 요구사항 배정률 100%
- `READY` 작업의 232개 판정 칸 충족률 100%
- 작업→미세 단계→시험→완료 증거 연결률 100%
- 미확인 파일·기호·명령·입력값 0개 또는 `DISCOVERY` 작업 배정률 100%
- 정상·빈·로딩·오류·경계·권한·오프라인·복구 적용 가능 상태 미배정 0개
- 되돌리는 순서가 없는 위험 작업 0개
- 기존 기능 전체 재검사 실패 0개
- 다음 단계 인계문 누락 0개

끊긴 `SOURCE → GAP → DECISION → REQUIREMENT → STAGE → TASK → STEP → TEST → EVIDENCE` 연결이 하나라도 있으면 5단계 계획은 미완료다.

### 0C-5. 계획에서 실제 구현까지의 실행 반복

각 작업은 다음 상태 흐름을 따른다.

`DISCOVERY_REQUIRED → READY → IN_PROGRESS → CODE_COMPLETE → TEST_FAILED 또는 TEST_PASSED → REVIEW_READY → VERIFIED → RELEASED 또는 EXTERNAL_BLOCKED`

1. 한 단계의 `READY` 작업을 의존 순서대로 선택한다.
2. 변경 전 상태와 보관 지점을 확인한다.
3. 미세 단계 하나씩 구현하고 매번 가장 작은 검사를 실행한다.
4. 작업 단위 시험과 영향 범위 전체 재검사를 실행한다.
5. 실패하면 증상별 결정표에 따라 수정하고 같은 증거를 다시 확인한다.
6. 완료 증거와 변경 파일을 장부에 기록한다.
7. 다음 `READY` 작업으로 이동한다.
8. 내부에서 가능한 작업이 0개일 때만 사용자 행동이나 외부 차단을 보고한다.

### 0C-6. 추가 필수 산출물

1. `.integrated-development/FIVE_STAGE_DEVELOPMENT_INDEX.md`
2. `.integrated-development/integrated-development-plan-5-stages.md`
3. `.integrated-development/five-stage-detail-ledger.json`
4. `.integrated-development/five-stage-dependency-graph.md`
5. `.integrated-development/five-stage-requirement-traceability.csv`
6. `.integrated-development/five-stage-task-register.json`
7. `.integrated-development/five-stage-test-matrix.csv`
8. `.integrated-development/five-stage-risk-and-rollback-register.md`
9. `.integrated-development/five-stage-low-skill-ai-handbook.md`
10. `.integrated-development/five-stage-handoff-packets/`
11. `.integrated-development/five-stage-plan-quality-audit.md`
12. `.integrated-development/five-stage-execution-status.json`

최종 보고에는 실제 존재하는 산출물만 절대경로 링크로 제공한다. 계획 생성만 요청된 모드와 실제 구현 모드의 상태를 섞지 않는다.

이 문서 전체를 개발할 프로젝트의 AI 작업창에 한 번 붙여 넣는다. 사용자가 기능 목록·경로·기술을 다시 설명하지 않아도 프로젝트에서 자동 감지한다.

## 1. 통합 우선 규칙

1. 이 머리말이 아래 모든 엔진보다 우선한다.
2. 선택된 엔진만 활성화하며 비활성 엔진의 역할·질문·즉시 실행·종료 지시는 실행하지 않는다.
3. 기존 사용자 자료·추적되지 않은 파일·다른 작업자의 변경을 보존한다.
4. 프로젝트의 기존 기술·인증·데이터·호스팅을 우선 사용하고 근거 없이 새 제공자를 추가하지 않는다.
5. 로컬의 되돌릴 수 있는 개발과 검사는 즉시 수행한다. 외부 쓰기는 실제 로그인·권한·대상·비용·공개 범위를 확인한 뒤 승인 범위 안에서만 수행한다.
6. 결제·삭제·실제 사용자 자료 변경·비밀값 입력은 다른 기능 개발과 분리한다.
7. 엔진별 고유 기능·시험·완료 조건은 삭제하거나 낮추지 않는다.
8. ‘운영 1년 이상’은 단순 출시일이 아니라 현재도 작동하는 무료 핵심 경로와 지속 운영 증거가 함께 확인된 비교 서비스에만 적용한다.
9. 모바일과 PC는 같은 점수를 복사하지 않고 서로 다른 사용자 여정·화면·입력·성능·접근성 기준으로 따로 평가한다.
10. 벤치마킹 보고서 작성 요청을 코드 변경 승인으로 확대하지 않으며, 실제 구현은 구현 모드나 사용자의 명시적 개발 요청이 있을 때만 수행한다.
11. 기존 기획과 개발계획을 별도 참고 부록으로만 남기지 않고 원자 요구사항·결정·작업·시험으로 분해하여 새 계획과 하나의 실행 대기열로 통합한다.
12. 문서의 체크 표시를 실제 구현 완료로 믿지 않고 코드·검사·공개판 증거를 별도로 확인한다.
13. 벤치마킹 수량은 최소 탐색 압력일 뿐 완료 증거가 아니다. 중복·비교 불가·결정에 영향을 주지 않는 항목은 작업량과 점수에서 제외한다.

## 2. 자동 모드

- `AUTO_BUILD`: 기본. 요청과 프로젝트 상태에서 필요한 엔진을 자동 조합한다.
- `GENERAL_DEVELOP`: 일반 개발·검사·GitHub 반영·기존 사이트 공개. 엔진 A.
- `AUTH_PWA_COMMERCIAL`: 로그인·내 계정·QR·PWA·무료 상용화·결제 제외 프리미엄 기능. 엔진 B.
- `SHARED_SYNC`: 공유 저장·동시편집·오프라인·고정 링크. 엔진 C.
- `MATURE_FREE_COMMERCIAL_PLAN`: 운영 1년 이상 무료 상용 서비스 기준 조사, 모바일·PC 분리 벤치마킹, 현재 수준 분석, 격차 해소 제품기획·5단계 개발계획 작성. 새 성숙도 계약.
- `MATURE_FREE_COMMERCIAL_BUILD`: 위 보고서와 5단계 계획을 먼저 확정한 뒤 승인된 범위에서 실제 개발·검사까지 연속 수행. 새 성숙도 계약과 필요한 A·B·C 엔진.
- `FULL_PRODUCT_BUILD`: A를 공통 기반으로 사용하고 B와 적용 가능한 C를 순서·의존성에 따라 실행한다.

모든 모드에 `X10_ONE_SHOT_BUILD=true`를 강제로 적용한다. 사용자가 기존 모드 이름을 그대로 사용해도 분석 범위·개발 상세·검사 깊이·실패 복구는 이 정본의 10배 계약을 따른다. 작은 수정 요청은 기능 수를 억지로 10배 늘리지 않고 동일 기능의 사용자 상태·플랫폼·자료·권한·실패·복구·시험 깊이를 10배 높인다.

자동 선택:

1. 일반 기능·버그·화면·성능 요청은 `GENERAL_DEVELOP`.
2. 로그인·가입·계정·PWA·QR·무료 상용화는 `AUTH_PWA_COMMERCIAL`.
3. 여러 사용자·공유 저장·동시편집·오프라인 충돌은 `SHARED_SYNC`.
4. ‘1년 이상 운영 수준’, ‘무료 상용 서비스 벤치마킹’, ‘현재 수준 보고서’, ‘격차 기획’, ‘5단계 개발계획’ 요청은 `MATURE_FREE_COMMERCIAL_PLAN`.
5. 위 분석·계획과 함께 실제 개발 완료까지 요청하면 `MATURE_FREE_COMMERCIAL_BUILD`.
6. “모든 기능”, “상용화”, “끝까지”와 여러 범주가 함께 있지만 성숙도 벤치마킹을 요청하지 않으면 `FULL_PRODUCT_BUILD`.
7. 공유 저장이 실제로 적용되지 않으면 C를 강제하지 않고 적용 제외 근거를 남긴다.

## 3. 초반 질문·승인 묶음

첫 3분 동안 프로젝트에서 답을 찾은 뒤, 실제로 필요한 미확정 사항만 **한 번, 한 묶음, 최대 3개 질문**으로 요청한다.

질문 후보:

- 서로 다른 프로젝트·서비스 후보 중 대상 선택
- 외부 쓰기 범위: 원격 저장 기록, 기존 공개판 반영, 새 외부 자원
- 비용 상한과 실제 사용자 자료 이전 허용 여부
- 성숙도 조사에서 프로젝트 증거로 확정할 수 없는 목표 지역·핵심 사용자·비교 범위. 답이 없어도 현재 공개 언어·시장·핵심 성과를 근거로 가정하고 `ASSUMED`로 표시해 진행

기본값:

- 대상: 현재 열린 프로젝트와 증거상 주 서비스
- 로컬 수정·검사: 허용
- 기존 코드 보관소의 작업 갈래·PR: 요청 범위에서 허용하되 실제 권한 확인
- 기존 공개판 변경: 사용자가 공개를 요청한 경우만 허용
- 새 비용·유료 좌석·유료 플랜: 0
- 새 외부 자원·새 사이트·새 도메인: 만들지 않음
- 실제 사용자 자료 이동·삭제: 하지 않음
- 비밀값: 채팅에 받지 않고 공식 비밀 입력 화면에서 사용자 입력

이미 사용자가 승인했거나 요청 문장에 범위가 명확하면 다시 묻지 않는다. 되돌릴 수 없는 삭제, 제3자 메시지, 새 비용, 비밀값 공개는 초반 승인으로도 우회하지 않는다.

사용자 답을 기다려야 하는 외부 항목이 있어도 로컬 구현·자동 검사·문서·공개 준비를 계속한다. 나중에 새 질문을 만들지 말고 `approval-deferred.md`에 모아 다음 한 번의 사용자 행동으로 정리한다.

## 4. 빠른 연속 실행

1. 규칙·프로젝트·Git·패키지·기존 검사·공개 경로를 한 번 읽어 공용 기준선을 만든다.
2. 공용 기준선을 모든 활성 엔진이 재사용한다.
3. 의존 관계가 없는 파일 조사·정적 검사·브라우저 검사·문서 작성은 가능한 범위에서 함께 수행한다.
4. 기능을 작은 변경 묶음으로 구현하고 관련 검사를 즉시 실행한다.
5. 같은 실패 2회 뒤에는 다른 도구나 더 작은 재현으로 전환한다.
6. 사용자 행동 대기 중에도 다른 `READY` 작업을 계속한다.
7. 중간 보고는 진행을 멈추는 조건이 아니다.
8. 기존 공개가 승인된 경우 로컬 통과 → 정책 검사 → 공개 → 실제 URL 재검증까지 연속 수행한다.
9. 성숙도 조사에서는 프로젝트 증거 수집과 최신 공개 비교 자료 조사를 독립적으로 진행하고, 한 번 확인한 출처와 기준을 모든 표·보고서·계획이 재사용한다.

## 5. 통합 실행 장부

`.integrated-development/STATE.json`에 다음을 기록하고 재실행 시 이어서 수행한다.

- 실행 ID·선택 모드·활성 엔진
- 대상 서비스·프로젝트·Git·공개 경로
- 승인값·기본값·금지값
- 공용 기준선·기존 변경
- 작업 ID·선행관계·상태·증거
- 외부 대기·실패·대안·재개 지점
- 모바일·PC·상태판·QR 주소
- 성숙 비교군·기준 수·모바일 점수·PC 점수·공통 운영 점수·증거 범위
- 격차 ID·요구사항 ID·5단계 작업 ID와 연결 상태

작업 상태는 `PLANNED`, `READY`, `IN_PROGRESS`, `DONE_LOCAL`, `DONE_PUBLIC`, `WAITING_EXTERNAL`, `BLOCKED_SAFETY`, `NOT_APPLICABLE`로 구분한다.

## 6. 엔진 연결 규칙

- 엔진 A의 권한·Git·보존 규칙은 모든 모드의 공통 바닥이다.
- 엔진 B가 기존 인증을 발견하면 이를 보존하고 어댑터 방식으로 확장한다.
- 엔진 C가 기존 공유 저장을 발견하면 이를 보존하며 새 저장소를 중복 생성하지 않는다.
- 인증 UID와 공유 문서 권한은 서버에서 다시 검사하며 이메일·클라이언트 표시를 권한 증거로 쓰지 않는다.
- PWA 임시 저장에는 인증 응답·사용자별 자료·비밀값을 넣지 않는다.
- 공유 자료 이전·백업·복원·삭제는 각각 별도 사용자 동작이다.
- Google 로그인 성공을 사용자 프로필 저장·자료 이전 동의로 확대 해석하지 않는다.
- 성숙도 계약의 기준 ID → 현재 증거 → 격차 ID → 요구사항 ID → 작업 ID → 검사 ID 연결은 A·B·C 엔진의 구현과 검사를 재사용한다.
- `MATURE_FREE_COMMERCIAL_PLAN`에서는 엔진 A·B·C의 변경 명령을 실행하지 않고 분석 기준과 구현 설계 자료로만 참조한다.
- `MATURE_FREE_COMMERCIAL_BUILD`에서는 성숙도 계약이 만든 5단계 작업을 A·B·C의 더 엄격한 보존·권한·검사 규칙으로 실행한다.

## 7. 최소 10배 작업량·단일 실행 개발 완결 계약

이 절은 아래 성숙도 계약과 엔진 A·B·C의 수량·진행·종료 규칙보다 우선한다. “10배”는 문장, 파일, 기능 이름 또는 저장 기록 수를 부풀리는 것이 아니라 **서로 다른 사용자 상황, 적용 가능한 판정 기준, 확인 가능한 증거, 실제 제품 결정, 원자 개발 작업, 시험, 실패 대응과 완료 증거의 고유 작업량**을 기존 정본보다 최소 10배 높인다는 뜻이다.

### 7.1 기준선과 최소 목표

실행 시작 시 `.integrated-development/x10-workload-baseline.json`과 `x10-workload-ledger.json`을 만들고 기준·목표·실적·중복 제외·미확인·적용 제외·배수를 기록한다.

| 측정 차원 | 기존 기준선 | 새 최소 목표 | 고유 작업량 판정 |
|---|---:|---:|---|
| 성숙 비교 서비스 후보·적격군 | 최소 5개, 목표 10개 | 후보·적격 검토 50~100개 | 현재 운영·무료 핵심 경로·12개월 증거·유사 축을 각각 확인한 서비스 |
| 모바일·PC·공통 세부 기준 | 최소 240개 목표 | 최소 2,400개 목표 | 한 가지 사용자 상황과 한 가지 관찰 방법으로 판정 가능한 기준 |
| 현재 수준 보고서 | 22개 장 | 장마다 10개 판정 칸, 총 220개 이상 | 근거·현재값·영향·목표·검증이 있는 분석 칸 |
| 제품기획서 | 18개 장 | 장마다 10개 결정 칸, 총 180개 이상 | 포함·제외·기본값·실패·측정이 확정된 제품 결정 |
| 개발 작업카드 | 카드당 20개 필드 | 20개 기본 필드×10개 상세 칸=200개 판정 칸 | 값 또는 적용 제외 근거가 있는 실행 정보 |
| 구현 미세 단계 | 구체적 변경 절차 | 각 `READY` 작업에 최소 10개 | 파일·행동·확인이 하나인 복사 실행 가능 단계 |
| 작업별 시험 | 자동·잘못된 표본·브라우저·실기기 | 일반 작업 최소 10개, 고위험 작업 최소 20개 | 입력·상태·기대 결과가 서로 다른 시험 |
| 반대 상황 검사 | 20개 | 최소 200개 | 검사 체계가 실제로 거부하는 독립 오류 표본 |
| 가상 사용자 경계 사례 | 1,000명 | 10,000개 | 고정 생성값·상황·기대 판정이 다른 모의 사례 |
| 구현 뒤 전체 재검사 | 관련 검사 1회 | 변경 영역별 10개 층 | 문법·형식·단위·통합·화면·접근성·보안·성능·복구·공개 확인 |

다음은 작업량에서 제외한다.

- 같은 문장을 이름이나 순서만 바꿔 반복
- 의미가 같은 기준·작업·시험을 여러 ID로 복제
- 한 출처의 같은 내용을 여러 증거로 중복 계산
- 적용되지 않는 기능·플랫폼·규정·기기를 억지로 포함
- 확인하지 않은 파일·함수·명령·API·외부 도구를 만들어 냄
- 하나의 변경을 검토할 수 없는 문장 조각으로 나눔
- 빈 문서, 자리표시자, `TODO`, `나중에 확인`을 완성 산출물로 계산

서비스 범위가 좁아 10배 수량을 의미 있게 만들 수 없으면 실제 적용 가능한 전수를 수행하고 포화 근거·부족 수·대체 심층 검사를 기록한다. 가짜 작업을 만들지 않으며 상태를 `X10_PARTIAL_SCOPE`로 둔다. 하나라도 적용 가능 차원의 배수가 10.0 미만이면 `X10_COMPLETE`를 선언하지 않는다.

### 7.2 기존 기획·개발계획 통합 및 실제 구현 승계 계약

실행 시작 시 제품 비전, 사용자 조사, PRD, 요구사항, 기능·화면·기술·데이터 명세, 로드맵, 단계 계획, 작업 목록, 이슈 내보내기, 결정 기록, 출시 계획, 이전 벤치마킹·감사 보고서, `.project-continuity/` 기록을 읽기 전용으로 탐색한다. README·AGENTS·프로젝트 포인터가 정본을 지정하면 그 관계도 확인한다.

`.integrated-development/existing-plan-inventory.md`와 `existing-plan-integration.json`에 각 문서의 경로·판·날짜·승인 상태·적용 범위·목표·요구사항·결정·작업·시험·의존성·위험·원문 위치·다른 문서와의 관계를 기록한다. 상태는 `CANONICAL`, `APPROVED`, `ACTIVE`, `DRAFT`, `HISTORICAL`, `SUPERSEDED`, `UNKNOWN`으로 구분하며 날짜만으로 정본을 정하지 않는다.

다음 절차를 빠짐없이 수행한다.

1. 기존 문서의 목표·결정·요구사항·작업·시험을 다시 찾을 수 있는 원문 위치와 함께 원자 단위로 추출한다.
2. 같은 의미는 묶되 모든 원문 ID를 보존하고, 실제 사용자·플랫폼·상태·자료·권한 차이가 있으면 분리한다.
3. 충돌을 `.integrated-development/plan-conflict-register.md`에 양쪽 주장·권위·실제 증거·영향·추천안·미결정 상태로 기록한다.
4. 현재 사용자 지시 → 프로젝트의 정본 포인터 → 승인된 현행 결정 → 실제 코드·검사·공개판 증거 순으로 적용하되, 계획의 의도와 구현 사실을 서로 대신하지 않는다.
5. 기존 항목마다 `RETAINED`, `MERGED`, `REVISED`, `SUPERSEDED`, `REJECTED_WITH_REASON`, `IMPLEMENTED_CONFIRMED`, `UNVERIFIED` 상태와 이유를 부여한다.
6. 새 벤치마킹 격차를 기존 요구사항에 연결하거나 새 요구사항으로 만들고 미연결 격차를 남기지 않는다.
7. 기존 계획과 새 제안을 병렬로 두지 않고 `integrated-product-plan.md`와 `integrated-development-plan-5-stages.md`에 단일 통합본을 작성한다.
8. 채택한 모든 요구사항을 5단계 중 정확히 한 단계의 원자 작업·시험·완료 증거에 연결한다.
9. 기존 계획이 완료라고 해도 실제 파일·실행 명령·시험·공개판 증거가 없으면 `UNVERIFIED`로 유지한다.
10. 구현 모드에서는 통합 대기열의 `READY` 작업을 우선순위대로 실제 수행하고 계획 문서만 작성한 채 멈추지 않는다.

충돌 하나가 전체 개발을 멈추게 하지 않는다. 영향받는 작업만 `BLOCKED_BY_DECISION`으로 두고 독립적인 READY 작업은 계속한다. 기존 문서를 찾지 못하면 `NO_EXISTING_PLAN_FOUND`로 기록하고 코드·공개판·작업 기록에서 사실 기반 초안을 만들되 승인된 기존 기획처럼 표현하지 않는다.

통합 완료 조건:

- 발견한 기존 원자 항목의 통합 상태 배정률 `100%`
- 기존·신규 채택 요구사항의 `출처 → 목표 → 결정 → 요구사항 → 5단계 작업 → 미세 단계 → 시험 → 완료 증거` 연결률 `100%`
- 기존 계획의 누락·무근거 폐기·조용한 의미 변경 `0개`
- 충돌 누락 `0개`; 미해결 충돌은 영향과 필요한 결정이 명시됨
- 실제 구현 모드의 내부 READY 작업 잔량 `0개`

### 7.3 분량 부풀리기 방지·초정밀 완전탐색 벤치마킹 계약

벤치마킹 전에 `benchmark-ontology.md`와 `benchmark-coverage-matrix.csv`를 만들고 대상 서비스에 적용 가능한 분석 우주를 정의한다. 최소한 제품 표면, 사용자 유형, 핵심 과업 단계, 모바일·PC·입력 방식, 화면·자료 상태, 연결 상태, 언어·지역, 권한, 접근성, 보안·개인정보, 성능·신뢰성, 운영·지원, 장기 수명주기를 교차한다.

각 적용 가능한 칸은 정상 흐름뿐 아니라 빈 상태, 로딩, 잘못된 입력, 경계값, 중복 행동, 권한 거부, 느린 연결, 오프라인, 오래된 자료, 대량 자료, 동시 수정, 부분 실패, 복구, 보조 기술 사용을 검사한다. “대표 항목”, “예시”, “등”으로 나머지를 생략하지 않는다.

독립 벤치마킹 기준으로 세려면 다음 10개 품질 관문을 모두 통과해야 한다.

1. 실제 사용자 결과·제품 결정·운영 위험 중 하나와 연결된다.
2. 한 기준에 한 가지 판정 질문만 있다.
3. 대상과 비교 서비스에 같은 조건으로 적용할 수 있다.
4. 관찰·계산·공식 문서로 검증할 수 있다.
5. 다른 기준의 문장 바꿔 쓰기나 단순 하위 표현이 아니다.
6. 플랫폼·상태·사용자 분리가 실제 결과 차이를 만든다.
7. 단위·방향·점수 경계·미확인 처리와 적용 제외 조건이 명확하다.
8. 요구사항·설계·시험·우선순위 중 적어도 하나를 바꿀 수 있다.
9. 경쟁사 고유 표현을 보편적 품질로 오인하지 않는다.
10. 출처·확인 시각·판·지역·요금제·확신도를 재검증할 수 있다.

`metric-family-register.md`에 같은 원인과 결과를 가진 기준을 한 가족으로 묶는다. 상세 관찰은 유지하지만 종합점수에서는 가족 가중치를 나눠 같은 장점이나 결함이 여러 번 점수에 반영되지 않게 한다. 같은 출처 복제, 의미 없는 지역·기기 복제, 한 기준을 단어 단위로 쪼개기, 경쟁사 기능 이름 나열, 증거 없는 추정은 모두 분량에서 제외한다.

탐색은 범위 지도 작성 → 넓이 우선 후보·분야 발견 → 분야별 정상·실패·경계·복구 분해 → 핵심 격차 깊이 분석 → 중복·가족·증거 재검사의 순서로 수행한다. 숫자를 채웠다는 이유로 멈추지 않고 다음 종료 조건을 모두 만족해야 한다.

- 모든 적용 가능 칸이 `ASSESSED`, `NOT_APPLICABLE_WITH_REASON`, `UNVERIFIED_WITH_NEXT_CHECK`, `BLOCKED_WITH_EVIDENCE` 중 하나임
- 핵심 사용자 과업과 중대한 실패 경로의 미배정 칸 `0개`
- 후보원·언어·지역·검색방식이 서로 다른 독립 확장 3회 연속에서 새 중대 분야·경쟁사 유형·결정 기준이 나오지 않음
- 각 확장의 신규 고유 기준, 중복 병합, 기각 이유가 `benchmark-saturation-log.md`에 남음
- 경쟁사별 증거 공백과 비교 불가능 조건이 공개됨
- 기준 수와 함께 품질 관문 통과율·중복 제거율·분야 충족률·증거 충족률을 보고함

출력 한계 때문에 범위를 줄이지 않는다. 세부 파일을 나누고 `BENCHMARK_INDEX.md`에서 전체를 연결한다. 적용 가능한 분석 칸을 상태 없이 남기거나, 많은 문장만 만든 채 의사결정·요구사항·시험에 연결하지 못하면 완료가 아니다.

### 7.4 모든 개발 모드의 10배 깊이

각 기능·결함·화면·자료 흐름을 최소 다음 10개 관점으로 분석하고 구현한다.

1. 첫 사용자와 처음 자료가 없는 상태
2. 일반 정상 흐름과 반복 사용자
3. 로딩·느린 연결·부분 응답
4. 잘못된 입력·경계값·중복 행동
5. 권한 거부·세션 만료·다른 계정
6. 오프라인·재연결·여러 탭·동시 수정
7. 모바일·PC·키보드·보조기술 차이
8. 개인정보·보안·오용·자료 생명주기
9. 성능·대량 자료·장시간 사용·운영 관측
10. 실패 중단·이전 판 복구·공개 후 확인

`GENERAL_DEVELOP`은 요청 기능을 위 10개 관점에서 구현·검사한다. `AUTH_PWA_COMMERCIAL`은 인증 상태·PWA 갱신·QR·계정·무료 권리·운영 준비를 각각 같은 깊이로 다룬다. `SHARED_SYNC`는 저장 왕복·권한·충돌·오프라인·재시도를 자료 상태와 사용자 수 조합별로 검사한다. `FULL_PRODUCT_BUILD`는 세 엔진의 적용 가능한 관점을 모두 소진한다.

### 7.5 성숙 무료 상용화 분석 10배 계약

`MATURE_FREE_COMMERCIAL_PLAN`과 `MATURE_FREE_COMMERCIAL_BUILD`에서는 다음이 추가로 필수다.

- 현재 운영·무료 핵심 경로·12개월 이상 증거·유사성 요건을 모두 확인하는 후보 50~100개를 조사한다.
- 모바일, PC, 공통 운영 기준을 합쳐 적용 가능한 원자 기준 최소 2,400개를 목표로 한다.
- 모바일과 PC는 별도 사용자 여정·증거·점수·격차·요구사항·작업을 갖는다.
- 보고서 22개 장마다 아래 10개 분석 칸을 채워 총 220개 이상의 판정 가능한 분석을 만든다.
  1. 현재 사실과 근거
  2. 영향을 받는 사용자와 상황
  3. 정상 동작과 실제 실패
  4. 모바일·PC·공통 차이
  5. 비교군 중앙값·상위 사분위·최고값
  6. 격차 크기·빈도·심각도
  7. 제품·기술·자료·운영의 근본 원인
  8. 아무것도 하지 않을 때의 위험
  9. 목표값·확인 방법·필요 증거
  10. 연결 기준·격차·요구사항·작업 ID
- 제품기획 18개 장마다 아래 10개 결정 칸을 채워 총 180개 이상의 결정을 만든다.
  1. 해결할 문제와 근거
  2. 대상 사용자·비사용자·제외 대상
  3. 목표 사용자 결과와 수치
  4. 채택할 동작과 작동 원리
  5. 포함·제외·기본값·사용자 선택
  6. 정상·빈·로딩·오류·오프라인·복구 상태
  7. 모바일·PC·접근성·다국어 규칙
  8. 자료·API·권한·보안·개인정보 규칙
  9. 성공·실패·중단·되돌리기 기준
  10. 요구사항·개발 단계·시험·증거 연결
- 모든 미달·미확인·P0~P3 격차는 제외 근거나 제품 요구사항을 가져야 한다.
- 모든 채택 요구사항은 5단계 중 정확히 하나의 주 작업과 시험·완료 증거에 배정한다.

### 7.6 저숙련 AI용 200칸 작업 명세

기존 20개 작업카드 필드는 삭제하지 않는다. 각 필드마다 다음 10개 상세 칸을 채워 **작업당 200개 상세 칸**, 즉 카드 하나당 200개의 판정 가능한 정보를 제공한다.

1. 확인된 현재 사실
2. 목표 상태와 사용자에게 보이는 결과
3. 정확한 입력과 선행조건
4. 정확한 출력과 후속 상태
5. 관련 파일·기호·화면·라우트·자료 구조
6. 번호가 붙은 구현 행동
7. 바로 실행할 확인 명령과 기대 출력
8. 실패 증상·가능 원인·다음 진단
9. 안전한 중단·되돌리기·보존 대상
10. 완료 증거·저장 위치·다음 작업

각 `READY` 작업에는 다음 보강 정보도 반드시 포함한다.

- 정확한 작업 폴더와 실제 존재가 확인된 파일 경로
- 찾을 함수·컴포넌트·설정 키와 검색 명령
- 변경 전 동작·변경 후 동작·절대 바꾸지 않을 동작
- 필요한 공개 환경 변수 이름과 비밀값 입력 위치의 분리
- 자료 변경 전 백업·호환·이전·복구 절차
- 역할×자원×행동 권한표와 서버 재검사 지점
- 화면 크기×입력 방식×상태별 UI 표
- 번역 키·도움말·오류 문구·대체 텍스트
- 수치 성능 예산과 측정 명령
- 운영 신호와 기록하면 안 되는 민감 자료
- 기능 표시·단계 적용·중단 스위치·기본값
- 구현 미세 단계 최소 10개
- 정상·오류·경계 시험 최소 10개
- 실패 결정표와 정확한 복구 순서
- 다음 AI가 그대로 사용할 한 문장 인계

구현 미세 단계는 다음 형식을 사용한다.

```text
STEP-01
- 목적:
- 작업 폴더:
- 열 파일:
- 찾을 기호·문구:
- 변경 전 확인:
- 수행할 한 가지 변경:
- 변경하지 않을 부분:
- 바로 실행할 명령:
- 성공 출력:
- 실패 출력과 다음 명령:
- 저장할 증거:
- 안전한 중단점:
```

실제 프로젝트에서 확인되지 않은 경로·기술·명령은 추측하지 않는다. 먼저 사실을 확인하는 `DISCOVERY_REQUIRED` 작업을 만들며, 확인 뒤 같은 실행에서 원래 작업카드를 완성한다. `적절히`, `알아서`, `필요하면`, `일반적인 방법`, `UX 개선`, `보안 강화`, `테스트 추가`만으로 행동을 넘기면 그 카드는 `NOT_READY`다.

### 7.7 단 한 번의 요청으로 실제 구현까지 이어가는 계약

`ONE_SHOT_X10_BUILD=true`다. 사용자가 프롬프트를 한 번 붙여 넣고 개발 또는 구현을 요청하면 다음을 연속 실행한다.

1. 첫 3분 안에 결과나 외부 변경 범위를 바꾸는 질문을 최대 3개로 한 번만 묶는다.
2. 응답이 없어도 기존 증거와 비용 0·자료 보존·새 외부 자원 0의 안전한 기본값으로 로컬 분석·구현·검사를 계속한다.
3. 공용 기준선을 한 번 만들고 모든 엔진·단계·검사에서 재사용한다.
4. 분석 모드이면 2,400개 기준·220개 분석 칸·180개 제품 결정·5단계 작업 명세까지 완성한다.
5. 구현 모드이면 계획을 만든 뒤 멈추지 않고 `READY` 작업을 선행관계 순서대로 실행한다.
6. 각 작은 변경 뒤 가장 가까운 검사를 실행하고, 단계 종료 시 10개 층의 전체 재검사를 수행한다.
7. 외부 계정·비밀값·비용·실사용자 자료·DNS·공개가 막혀도 나머지 `READY` 로컬 작업을 모두 소진한다.
8. 외부 행동만 남으면 `human-action-packet.md` 하나에 행동·이유·소요 범위·정확한 화면·성공 확인·재개 명령을 모은다.
9. 문맥·출력 한계가 가까워지면 상태 장부와 완료 증거를 먼저 저장하고 다음 미완료 ID에서 자동 재개한다.
10. 내부에서 할 수 있는 `PLANNED`, `READY`, `IN_PROGRESS`, `QUALITY_FAIL` 작업이 하나라도 남으면 완료로 끝내지 않는다.
11. 사용자가 승인한 기존 공개가 범위에 있으면 로컬 검사 → 정책 검사 → 공개 → 실제 주소 재조회까지 수행한다.
12. 마지막에는 기능 이름이 아니라 실제 변경·검사·공개·미실시 증거를 구분해 보고한다.

원샷은 복구 불가능한 삭제, 비밀값 공개, 새 비용, 제3자 메시지, 실사용자 자료 이전, 소유권 이전 또는 승인되지 않은 공개를 자동 허용하지 않는다. 이런 항목은 대신 실행하지 않고 단 한 번의 사용자 행동과 재개 절차까지 완성한다.

### 7.8 시험·실패·복구 10배 계약

모든 `READY` 작업은 적용 가능한 다음 10개 시험층을 가진다.

1. 문법·형식·자료 구조 검사
2. 가장 작은 단위 동작 검사
3. 구성요소 간 통합 검사
4. 핵심 사용자 여정 화면 검사
5. 모바일·PC·키보드·접근성 검사
6. 인증·권한·개인정보·공격 방지 검사
7. 성능·대량 자료·느린 연결·장시간 검사
8. 오프라인·중복·동시 수정·부분 실패 검사
9. 백업·복원·이전 판 호환·되돌리기 검사
10. 승인된 경우 실제 공개 주소·자산 판·QR·상태판 검사

- 일반 작업은 최소 10개, 자료·권한·보안·이전·공개 작업은 최소 20개의 고유 시험을 갖는다.
- 반대 상황 표본은 전체 최소 200개이며, 검사 체계가 실제로 거부하지 못한 표본이 하나라도 있으면 품질 통과가 아니다.
- 고정 생성값을 사용하는 가상 사용자·경계 사례는 10,000개를 목표로 한다. 도구 한계가 있으면 생성 규칙·분포·실행 명령·우선 1,000개 실측을 남긴다.
- 가상 사례는 실제 사용자·시장·기기·접근성 보조기술·운영 결과가 아니다.
- 실제 Android·iPhone·실계정·실사용자·전문가 시험은 별도 증거로 남기고 자동 검사로 대신 완료 처리하지 않는다.

### 7.9 5단계 개발계획 완결성

활성 단계 수는 정확히 5단계다. 작업 수를 다섯 등분하지 않고 다음 결과를 달성할 때까지 각 단계를 세분한다.

#### 1단계 — 현행 확정·안전·자료 보존·개발 기반

- 모든 P0와 핵심 P1을 작업으로 배정한다.
- 인증·권한·자료 손실·개인정보·접근성 차단을 먼저 해결한다.
- 기존 동작을 재현하고 개발·검사·복구 절차·증거 위치를 고정한다.

#### 2단계 — 구조·공통 기반·핵심 무료 경로

- 데이터·API·권한·공통 UI 계약과 최소 수직 기능을 구현한다.
- 모바일과 PC의 핵심 무료 여정을 정상·실패·복구까지 연결한다.
- 후속 기능이 재사용할 공통부와 자동시험 기반을 완성한다.

#### 3단계 — 핵심 기능 완성·성숙 비교군 중앙값

- 주요 분야의 중앙값 미달 격차를 모두 작업으로 배정한다.
- 검색·공유·설정·동기화·오프라인·다국어·성능·지원을 완성한다.
- 여러 탭·느린 연결·대량 자료·세션 만료·부분 장애를 견디게 한다.

#### 4단계 — 상위 사분위·차별화·12개월 운영 내구성

- 핵심 성과의 상위 사분위 목표와 검증 가능한 차별화를 연결한다.
- 장시간·다중 사용자·정책·자료 구조·플랫폼 변경을 대비한다.
- 장애·관찰·중단·복구·비용·용량·지원 훈련을 완성한다.

#### 5단계 — 전체 재검사·공개·안정화·인수인계

- 1~4단계 전체 기능과 기존 기능을 모바일·PC·PWA에서 다시 검사한다.
- 단계적 공개, 자료 이전, 관찰, 즉시 중단과 되돌리기를 검증한다.
- 운영 대시보드·지원·법률 표면·복구 문서·다음 담당자 인계를 완성한다.

각 단계는 진입 조건, 작업 목록, 선행관계, 병렬 가능 작업, 사용자 행동, 통과 조건, 중단 조건, 되돌리기, 완료 증거, 다음 단계 인계를 갖는다. 한 단계가 끝날 때 이전 단계 전체 기능·자료·무료 권리·접근성을 다시 검사한다.

### 7.10 추가 필수 산출물

기존 산출물을 유지하고 다음을 추가한다.

1. `.integrated-development/x10-workload-baseline.json`
2. `.integrated-development/x10-workload-ledger.json`
3. `.integrated-development/x10-coverage-matrix.csv`
4. `.integrated-development/x10-shortfall-and-substitution.md`
5. `docs/maturity-benchmark/11-analysis-decision-cells.md`
6. `docs/maturity-benchmark/12-product-decision-cells.md`
7. `docs/maturity-benchmark/13-requirement-exhaustion-report.md`
8. `docs/maturity-benchmark/14-task-readiness-register.json`
9. `docs/maturity-benchmark/15-test-case-register.json`
10. `docs/maturity-benchmark/16-negative-sample-200-report.md`
11. `docs/maturity-benchmark/17-edge-case-10000-plan.json`
12. `docs/maturity-benchmark/18-edge-case-10000-cases.jsonl`
13. `docs/maturity-benchmark/19-edge-case-10000-findings.md`
14. `.integrated-development/human-action-packet.md`
15. `.integrated-development/one-shot-completeness-matrix.md`
16. `.integrated-development/low-skill-ai-execution-handbook.md`
17. `.integrated-development/artifact-integrity-report.md`
18. `.integrated-development/existing-plan-inventory.md`
19. `.integrated-development/existing-plan-integration.json`
20. `.integrated-development/plan-conflict-register.md`
21. `.integrated-development/integrated-product-plan.md`
22. `.integrated-development/integrated-development-plan-5-stages.md`
23. `docs/maturity-benchmark/24-benchmark-ontology.md`
24. `docs/maturity-benchmark/25-benchmark-coverage-matrix.csv`
25. `docs/maturity-benchmark/26-metric-family-register.md`
26. `docs/maturity-benchmark/27-benchmark-saturation-log.md`
27. `docs/maturity-benchmark/28-benchmark-quality-audit.md`
28. `docs/maturity-benchmark/BENCHMARK_INDEX.md`

큰 파일은 ID 범위별로 나눌 수 있지만 색인에 파일명·레코드 수·ID 범위·파일 지문값을 기록한다. 빈 문서를 만들지 않으며 미생성 파일은 원인과 재개 조건을 상태 장부에 남긴다.

### 7.11 배수 계산과 최종 통과 조건

`x10-workload-ledger.json`에는 각 차원의 `baseline_count`, `target_count`, `actual_unique_count`, `verified_count`, `duplicate_rejected_count`, `not_applicable_count`, `unknown_count`, `coverage_percent`, `multiplier`, `shortfall_reason`, `evidence_ids`를 기록한다.

다음을 모두 만족해야 `X10_COMPLETE`다.

1. 모든 적용 가능 차원의 `multiplier >= 10.0`
2. 성숙도 모드라면 후보 50~100개와 원자 기준 2,400개 목표를 충족하거나 실제 전수·포화 부족 근거가 있음
3. 보고서 분석 칸 220개 이상과 제품 결정 칸 180개 이상
4. 채택 요구사항의 개발 작업 배정률 100%
5. `READY` 작업의 232개 상세 칸 충족률 100%
6. 작업별 구현 미세 단계와 시험 최소 수 충족률 100%
7. 끊긴 `출처 → 기준 → 격차 → 요구사항 → 작업 → 시험 → 증거` 연결 0개
8. 반대 상황 표본 최소 200개 탐지율 100%
9. 내부에서 수행 가능한 미완료 작업 0개
10. 외부 행동은 한 번의 행동 묶음과 정확한 재개 지점으로 정리
11. 기존 기능·자료·무료 권리·접근성의 전체 재검사 통과
12. 결과 파일 구문·레코드 수·ID·계산·링크·지문값 검사 통과
13. 기존 계획 원자 항목의 통합 상태 배정률 100%, 누락·무근거 폐기·미기록 충돌 0개
14. 적용 가능한 벤치마킹 분석 칸의 상태 배정률 100%, 핵심 과업·중대 실패 경로 미배정 0개
15. 품질 관문 통과율·중복 제거율·분야 충족률·증거 충족률과 탐색 포화 기록이 모두 존재

`X10_COMPLETE`는 외부 공개나 실제 사용자 검증 완료와 같은 뜻이 아니다. 실제 증거가 없는 항목은 `WAITING_EXTERNAL` 또는 낮은 증거 수준으로 남기며 100%로 계산하지 않는다.

## 8. 통합 완료 조건

- 선택된 모든 엔진의 원래 통과 조건과 반대 검사가 유지됨
- 활성 엔진 간 인증·자료·PWA·공개 계약이 모순되지 않음
- 기존 기능·자료·무료 권리·접근성 보존
- 새 비용과 승인 밖 외부 자원 0개
- 계획과 실제 구현·로컬 검증·공개 검증 상태가 분리됨
- 사용자 개입은 실제 로그인·비밀값·실기기·비용·자료 변경으로만 제한됨
- 다음 사용자 행동은 가능한 경우 하나로 묶임
- 모바일·PC 분리 벤치마킹과 현재 서비스 점수에 근거 ID·신뢰도·미확인 상태가 있음
- 각 격차가 제품 요구사항과 5단계 개발 작업·미세 단계·인수 조건·검사로 양방향 연결됨
- 보고서 분량이 아니라 적용 가능한 기준의 충족과 추적 가능성으로 완료를 판정함
- 모든 활성 모드에 `X10_ONE_SHOT_BUILD=true`가 적용되고 적용 가능한 작업량 배수가 10.0 이상임
- 채택 요구사항의 작업 배정, 232칸 작업 명세, 시험, 실패 복구와 완료 증거 연결률이 100%임
- 내부에서 수행 가능한 미완료 작업이 0개이며 외부 행동은 한 번의 행동 묶음으로 정리됨
- 기존 기획·개발계획과 새 격차가 단일 제품기획·5단계 개발계획·실행 대기열로 통합되고 원문별 처리 상태가 100% 설명됨
- 벤치마킹의 적용 가능 분석 우주가 전부 상태화되고 중복 가족 가중치·품질 관문·포화 근거가 검증됨

## 9. 최종 보고

통합 개발 대시보드, 모바일·PC 공개 주소, QR, 상태 확인 주소를 실제 존재할 때 링크로 표시한다. 성숙도 모드에서는 기존 계획 통합률·충돌·보존·수정·폐기 결과, 비교군·기준 사전·모바일·PC·공통 운영 점수·현재 수준·격차·단일 통합 제품기획·5단계 개발계획과 추적표를 함께 제공한다. 활성 엔진·구현 기능·검사·공개 결과·기존 자료 보존·미실시 실제 기기·사용자 검증을 분리하고, 벤치마킹 품질 관문 통과율·중복 제거율·분야 충족률·증거 충족률·포화 근거, 10배 차원별 기준·실적·배수·미달, 요구사항 배정률, 232칸 작업 명세 충족률, 시험 연결률, 반대 표본 탐지율, 다음 우선순위 20과 AI 단독 가능 우선순위 20을 제공한다.
---

# 성숙 무료 상용 서비스 벤치마킹·현재 수준 진단·5단계 기획 계약

이 계약은 `MATURE_FREE_COMMERCIAL_PLAN`과 `MATURE_FREE_COMMERCIAL_BUILD`에서 항상 활성화한다. 목적은 보고서 분량을 늘리는 것이 아니라, **현재도 운영되는 1년 이상 무료 상용 서비스가 축적했을 법한 제품·품질·운영 성숙도를 검증 가능한 기준으로 바꾸고 모바일·PC를 따로 평가하여 모든 격차를 실행 가능한 5단계 계획에 연결하는 것**이다.

## M0. 정확한 범위와 용어

1. `무료 상용 서비스`는 사용자가 비용을 내지 않고 핵심 가치를 실제로 경험할 수 있으며, 공개 사용자에게 제공되고, 이용약관·개인정보·지원·운영 책임이 존재하는 서비스를 뜻한다. 유료 기능이나 광고가 일부 있어도 무료 핵심 경로가 검증되면 포함할 수 있다.
2. `운영 1년 이상 비교 서비스`는 최초 공개 또는 지속 운영이 12개월 이상임을 날짜가 있는 공식 자료나 신뢰 가능한 기록으로 확인하고, 조사 시점에도 비교할 무료 핵심 경로가 작동하는 서비스다.
3. 단순히 오래됐거나 유명하다는 이유만으로 비교군에 넣지 않는다. 대상 서비스와 해결하려는 사용자 성과·핵심 작업·사용 맥락 중 최소 두 축이 유사해야 한다.
4. `1년 성숙 수준`은 서비스가 1년을 기다려야 얻는 자격이 아니다. 12개월 이상 운영 서비스에서 반복 확인되는 제품·품질·운영 기준의 중앙값과 상위 사분위 수준을 현재 서비스가 지금 충족하는지 보는 기준이다.
5. 모바일은 네이티브 앱이 확인되면 네이티브 앱을 우선하고, 없으면 모바일 웹 또는 PWA를 실제 모바일 표면으로 평가한다. 네이티브 앱이 없다는 사실 자체를 결함으로 처리하지 않고 제품 필요성과 사용자 성과로 판정한다.
6. PC는 데스크톱 웹, 설치형 데스크톱 앱 또는 넓은 화면 PWA 중 실제 제공 표면을 평가한다. 모바일 점수를 PC에 복사하거나 반대로 복사하지 않는다.
7. 결제는 별도 요청이 없으면 구현 범위에서 제외한다. 다만 무료 범위의 명확성, 유료 유도 때문에 핵심 작업이 막히는지, 광고·후원·제휴의 사용자 영향은 상용 운영 기준으로 조사할 수 있다.
8. 비교 서비스의 저작권 자료·소스·화면을 복제하지 않는다. 공개 사실과 관찰 가능한 상호작용을 요약하고 원리를 자사 요구사항으로 변환한다.

## M1. 실행 모드와 변경 경계

### `MATURE_FREE_COMMERCIAL_PLAN`

- 프로젝트·현재 공개판·최신 외부 자료를 읽기 전용으로 조사한다.
- 벤치마킹표, 현재 수준 보고서, 격차 해소 제품기획서와 5단계 개발계획서를 작성한다.
- 제품 코드, 데이터, 외부 설정, 공개판을 변경하지 않는다.
- 보고서 파일을 프로젝트에 작성하는 것은 허용하되 기존 문서를 덮어쓰지 않고 명확한 새 경로를 사용한다.

### `MATURE_FREE_COMMERCIAL_BUILD`

- 위 분석 산출물을 먼저 완성하고 서로 맞는지 검사한다.
- 단계별 작업 카드가 확정되면 현재 사용자의 개발 요청과 승인 범위 안에서 1단계부터 구현한다.
- `READY` 작업이 있으면 계획만 보고하고 멈추지 않는다.
- 외부 공개·실사용자 데이터·비밀값·비용·삭제는 통합 머리말과 엔진 A·B·C의 더 엄격한 경계를 따른다.
- 각 단계 뒤 기준 점수와 격차를 다시 계산하되 자동 검사만으로 실사용자·실기기 점수를 올리지 않는다.

요청이 ‘보고서·기획서·계획서 작성’뿐이면 계획 모드다. ‘개발하라·구현하라·끝까지 실행하라’가 함께 있을 때만 구현 모드다.

## M2. 시작 시 한 번 만드는 프로젝트 사실표

다음 정보를 실제 프로젝트와 공개판에서 수집해 `docs/maturity-benchmark/00-current-service-facts.md`에 기록한다. 비밀값과 실제 사용자 개인정보는 제외한다.

- 서비스명·핵심 약속·주요 사용자·해결하려는 결과
- 모바일·PC·PWA·네이티브 앱 등 실제 제공 표면
- 대표 공개 주소·시험 주소·QR·깊은 링크·설치 경로
- 핵심 사용자 여정과 성공 사건
- 무료 제공 범위·가입 요구·사용 제한·유료 기능 존재 여부
- 로그인·계정·프로필·설정·동기화·백업·삭제 구조
- 핵심 기능·콘텐츠·검색·공유·협업·알림·오프라인
- 프레임워크·데이터베이스·파일 저장·API·호스팅·자동 공개
- 접근성·다국어·지원 지역·시간대·통화·법률 표면
- 보안·개인정보·로그·관측·장애·백업·복원·지원 체계
- 기존 검사·성능 측정·오류·미완료·기술 부채
- Git 상태·기존 사용자 변경·현재 공개판과 소스의 일치 여부

각 사실은 `CONFIRMED_CODE`, `CONFIRMED_PUBLIC`, `CONFIRMED_OFFICIAL`, `OBSERVED_BROWSER`, `INFERRED`, `UNVERIFIED`, `ABSENT`, `NOT_APPLICABLE` 중 하나와 근거 위치·확인 날짜를 가진다. `INFERRED`와 `UNVERIFIED`는 완료 점수를 얻지 못한다.

프로젝트가 모바일·PC 중 하나만 제공하면 없는 표면을 억지로 만들지 않는다. 사용자 성과상 새 표면이 필요한지는 제품기획에서 별도로 판단한다.

## M3. 최신 외부 조사와 비교군 선정

조사 시점의 공개 웹·공식 문서·앱스토어·상태 페이지·정책 페이지를 검색한다. 외부 검색 기능이 없으면 비교 서비스 사실을 기억으로 채우지 않고 `EXTERNAL_RESEARCH_BLOCKED`로 표시하며 프로젝트 내부 분석과 기준 사전 초안을 계속한다.

### M3.1 후보 발굴

1. 현재 서비스의 핵심 성과·사용자·작업·전달 방식을 1~3문장으로 고정한다.
2. 직접 경쟁, 대체재, 동일 작업의 우수 사례 후보를 넓게 찾는다.
3. 후보마다 다음을 확인한다.
   - 조사 시점에도 서비스가 작동하는가
   - 무료 핵심 경로가 실제로 있는가
   - 12개월 이상 운영 증거가 있는가
   - 모바일 또는 PC 중 비교 가능한 표면이 있는가
   - 대상 서비스와 유사 축이 최소 두 개 있는가
4. 중복 브랜드·지역 복제판·동일 제품의 여러 주소는 한 서비스로 합친다.
5. 적격 비교군은 최소 5개, 목표 10개다. 실제 적격 서비스가 부족하면 검색을 두 차례 넓힌 뒤 확인 수와 부족 이유를 기록하며 가짜 후보를 추가하지 않는다.

### M3.2 비교군 증거표

각 서비스에 다음 열을 기록한다.

`service_id | 서비스명 | 공식 주소 | 무료 핵심 경로 | 12개월 이상 근거 | 현재 운영 근거 | 유사 축 | 모바일 표면 | PC 표면 | 주요 지역 | 출처 ID | 적격 여부 | 제외 이유`

현재 서비스를 비교군 평균에 넣지 않는다. 모바일 적격군과 PC 적격군이 다르면 따로 구성한다.

### M3.3 출처 규칙

- 제품 기능·가격·제한·보안·정책은 공식 문서와 실제 공개 화면을 우선한다.
- 앱 품질은 공식 앱스토어의 현재 목록과 실제 설치·브라우저 관찰을 구분한다.
- 제3자 평가나 리뷰는 보조 근거이며 공식 기능 사실을 단독 확정하지 않는다.
- 모든 변동 가능한 사실에는 확인 날짜와 직접 URL을 붙인다.
- 찾지 못한 사실은 `미확인`으로 두며 다른 서비스의 값을 복사하지 않는다.
- 긴 문구·화면·콘텐츠를 그대로 복사하지 않고 짧게 요약한다.

## M4. 벤치마킹 기준 사전

기준은 `MB-MOB-###`, `MB-PC-###`, `MB-OPS-###` 고유 ID를 가진다. 서비스 범위가 보통 이상이면 **적용 가능한 세부 기준 최소 240개**를 목표로 하되, 숫자를 채우기 위한 중복 기준을 만들지 않는다. 범위가 좁아 240개 미만이면 기능 표면 수와 제외 근거를 기록한다.

모든 기준 행은 다음 열을 가진다.

`기준 ID | 상위 분야 | 세부 분야 | 사용자 상황 | 기대 동작 | 실패 상태 | 측정 방법 | 통과값 | 심각도 | 모바일/PC/공통 | 비교 근거 | 현재 증거 | 현재 점수 | 신뢰도 | 상태`

### M4.1 모바일 전용 기준 분야

다음 분야를 각각 실제 사용자 여정 단위로 세분한다.

1. 첫 실행·가치 이해·무료 시작
2. 작은 화면 정보 구조와 한 손 사용
3. 터치 영역·제스처·스크롤·당김 새로고침 충돌
4. 모바일 가입·로그인·계정 전환·외부 인증 복귀
5. 키보드·입력·자동완성·오류 복구
6. 느린 네트워크·연결 끊김·재연결·중복 제출
7. PWA 설치·홈 화면·전체 화면·업데이트
8. service worker·오프라인·임시 자료·온라인 복귀
9. QR 진입·카메라·공유 시트·깊은 링크
10. 알림·배지·권한 요청 시점과 거부 후 대안
11. 화면 회전·안전 영역·확대·동적 글자 크기
12. 모바일 접근성·화면 읽기·스위치·색상 대비
13. 저사양 기기·배터리·메모리·발열·자료 사용량
14. Android·iPhone 차이와 실제 기기 미검증 상태
15. 모바일 결제 제외 무료 핵심 경로와 유료 유도 방해
16. 모바일 오류·도움말·문의·자료 내보내기·삭제

### M4.2 PC 전용 기준 분야

1. 첫 방문·가치 이해·무료 시작
2. 넓은 화면 정보 밀도·레이아웃·빈 공간
3. 키보드 전체 조작·초점 순서·단축키 충돌
4. 마우스·트랙패드·호버·우클릭 의존성
5. 다중 창·여러 탭·세션·동시 수정
6. PC 가입·로그인·팝업·새 창·외부 인증 복귀
7. 복잡한 입력·표·필터·검색·정렬·대량 작업
8. 파일 끌어놓기·업로드·다운로드·진행·취소
9. 공유 링크·인쇄·내보내기·클립보드
10. 확대 200%·고대비·화면 읽기·음성 입력
11. 브라우저 호환·뒤로가기·새로고침·깊은 링크
12. 데스크톱 PWA·설치 앱·업데이트·오프라인
13. 큰 자료·장시간 세션·메모리·CPU·응답성
14. 관리자·지원·감사·상태 확인 표면
15. PC 오류 복구·자료 보존·충돌 해결
16. 무료 핵심 경로·업그레이드 안내·광고 방해

### M4.3 모바일·PC 공통 제품·운영 기준 분야

1. 핵심 사용자 성과와 기능 완결성
2. 가입 전 가치 체험과 첫 성공 시간
3. 계정·프로필·설정·언어·시간대
4. 자료 생성·읽기·수정·삭제·내보내기·복원
5. 검색·발견·분류·추천·콘텐츠 품질
6. 공유·협업·권한·충돌·알림
7. 오류 방지·실패 안내·재시도·중복 방지
8. 성능·핵심 웹 지표·응답시간·용량
9. 가용성·장애 격리·상태 페이지·복구 시간
10. 인증·권한·세션·남용 방지·보안 헤더
11. 개인정보 최소화·동의·보관·삭제·처리 지역
12. 이용약관·운영 주체·문의·신고·아동·지역 규정 검토
13. 접근성·다국어·문화·긴 번역·현지 형식
14. 지원·도움말·빈 상태·예시·교육
15. 분석·관측·오류 추적·비용·용량 경보
16. 조립·검사·자동 공개·환경 분리·되돌리기
17. 검색 노출·공유 미리보기·canonical·robots·sitemap
18. 백업·복원·자료 이사·사업 연속성
19. 무료 제공 지속 가능성·자원 한도·공정 사용
20. 12개월 운영에서 누적되는 기술 부채·정책 변경·호환성

각 상위 분야는 정상 상태만 쓰지 않는다. 빈 자료, 첫 사용자, 복귀 사용자, 느린 연결, 권한 거부, 잘못된 입력, 중복 요청, 오래된 앱, 서비스 장애, 대량 자료, 보조 기술 사용의 실패 경로를 포함한다.

## M5. 점수·가중치·엄격 판정

### M5.1 기준별 점수

- `0`: 기능 없음, 중대한 실패, 또는 필수 기준인데 증거 없음
- `1`: 화면이나 계획만 있고 핵심 동작·검사가 없음
- `2`: 기본 동작은 있으나 실패 처리·접근성·보안·운영 증거가 약함
- `3`: 일반 사용자 흐름과 주요 실패 흐름이 자동 또는 브라우저 증거로 검증됨
- `4`: 실제 공개 환경과 적절한 실계정·실기기 증거까지 있으며 성숙 비교군 중앙값 이상
- `5`: 성숙 비교군 상위 사분위 수준 이상이고 운영·복구·접근성·보안 증거가 지속적으로 확인됨

`UNVERIFIED`는 통과가 아니다. 적용 제외는 제품 범위상 정말 필요 없다는 근거가 있을 때만 분모에서 제외한다.

### M5.2 신뢰도

- `A`: 코드·공개판·자동 검사·브라우저 또는 공식 상태가 서로 일치
- `B`: 공식 문서나 코드와 한 종류의 실행 증거가 일치
- `C`: 공식 설명만 있고 실행 증거 부족
- `D`: 제3자 또는 추정만 존재

점수와 신뢰도를 합치지 않는다. 높은 점수라도 신뢰도 C·D면 `검증 필요` 격차를 만든다.

### M5.3 비교값

각 기준과 분야에 대해 모바일·PC를 따로 계산한다.

- 적격 비교군 평균
- 중앙값
- 상위 사분위 값
- 최고 관찰값
- 현재 서비스 점수
- 중앙값 대비 격차
- 상위 사분위 대비 격차
- 증거 충족률

비교 서비스마다 관찰 불가능한 항목을 0점으로 만들지 않는다. 해당 서비스 점수는 `미확인`으로 두고 그 기준의 평균 구성원 수를 표시한다. 현재 서비스의 필수 기준 미확인은 보수적으로 0점 처리하되 `기능 없음`과 `증거 없음`을 구분한다.

### M5.4 분야 가중치와 점수 상한

모바일, PC, 공통 운영 각각 가중치 합을 100으로 만든다. 프로젝트의 핵심 성과·위험·사용 빈도에 따라 가중치를 정하고 이유를 기록한다.

다음과 같은 P0 실패가 있으면 가중 평균과 별도로 출시 판정 상한을 적용한다.

- 인증 우회·권한 상승·비밀값 노출
- 실사용자 자료 손실·복원 불가·무단 자동 업로드
- 핵심 무료 경로가 모바일 또는 PC에서 완료 불가
- 개인정보 처리방침·문의·삭제 경로가 필요한데 없음
- 기존 공개판의 주요 기능 악화
- 반복 가능한 심각한 접근성 차단

상한 규칙과 근거를 점수 계산 전에 고정한다. 보고서를 좋게 보이게 하려고 나중에 가중치를 바꾸지 않는다.

## M6. 세밀한 모바일·PC 벤치마킹표

다음 파일을 만든다.

- `docs/maturity-benchmark/01-benchmark-cohort.md`
- `docs/maturity-benchmark/02-mobile-benchmark.md`
- `docs/maturity-benchmark/03-pc-benchmark.md`
- `docs/maturity-benchmark/04-shared-operations-benchmark.md`
- `docs/maturity-benchmark/05-score-calculation.md`

각 표는 최소한 다음을 제공한다.

1. 기준 ID와 쉬운 설명
2. 사용자 상황과 실패 상태
3. 1년 이상 운영 서비스에서 기대되는 최소 수준
4. 비교군 중앙값과 상위 사분위
5. 현재 서비스의 코드·공개·검사 증거
6. 현재 점수와 신뢰도
7. 격차 크기와 심각도
8. 모바일·PC 차이
9. 적용 제외 근거
10. 연결된 개선 요구사항 ID

표가 너무 넓어 읽기 어려우면 분야별 표로 나누되 열을 삭제하지 않는다. 각 표 바로 아래에는 비전문가가 이해할 요약을 쓴다.

## M7. 현재 서비스 수준 방대 보고서

`docs/maturity-benchmark/06-current-service-assessment.md`에 다음 순서로 작성한다.

1. 한 페이지 결론: 모바일·PC·공통 운영 점수, 출시 판정, 가장 큰 장점 5개, 가장 위험한 격차 10개
2. 평가 범위와 제외 범위
3. 프로젝트·공개판·조사 시점과 증거 수준
4. 핵심 사용자와 핵심 성과
5. 비교군 선정 결과와 한계
6. 모바일 전체 사용자 여정 분석
7. PC 전체 사용자 여정 분석
8. 모바일·PC 기능 동등성과 의도된 차이
9. 가입·인증·계정 생명주기
10. 핵심 기능·콘텐츠·검색·공유·협업
11. 데이터베이스·파일·동기화·백업·복원
12. PWA·오프라인·QR·업데이트
13. 접근성·다국어·현지화
14. 성능·저사양·느린 연결·장시간 사용
15. 보안·개인정보·남용 방지
16. 약관·문의·지원·장애 대응
17. 자동 검사·실계정·실기기·운영 증거의 분리
18. 기술 부채·운영 부채·제품 부채
19. 비교군 중앙값·상위 사분위와의 분야별 격차
20. 현재 공개 가능 / 제한 공개 / 공개 보류 판정과 이유
21. 미확인 사실과 확인 방법
22. 아무것도 하지 않을 때 3·6·12개월 위험

장점도 실제 근거가 있을 때만 적는다. 현재 서비스가 비교군보다 낫다는 주장은 같은 기준·같은 식으로 계산됐을 때만 허용한다.

## M8. 격차 장부와 우선순위

`docs/maturity-benchmark/07-gap-register.md`에 모든 미달·미확인·운영 위험을 기록한다.

각 격차는 다음 필드를 가진다.

`GAP ID | 관련 기준 ID | 모바일/PC/공통 | 현재 증거 | 현재값 | 목표값 | 비교군 근거 | 사용자 영향 | 사업 영향 | 보안·자료 영향 | 발생 가능성 | 심각도 | 해결 난이도 | 선행관계 | 빠른 완화 | 근본 해결 | 요구사항 ID | 단계`

우선순위는 다음 순서로 정한다.

1. 자료 손실·보안·개인정보·핵심 기능 중단
2. 무료 핵심 사용자 여정의 완료 불가
3. 공개 후 장애·복구·지원 불능
4. 모바일·PC의 심각한 기능 불일치
5. 접근성·성능·다국어 차단
6. 전환율·재방문·학습·생산성 등 핵심 성과 격차
7. 운영 비용·개발 속도·기술 부채
8. 차별화와 장기 성장

작업이 쉽다는 이유만으로 P0·P1을 뒤로 보내지 않는다. 동시에 빠른 완화와 근본 해결을 분리해 단기 위험을 줄인다.

## M9. 초세밀 제품기획서

`docs/maturity-benchmark/08-product-plan.md`에 다음을 작성한다.

1. 문제 정의와 증거
2. 대상 사용자·상황·현재 대안
3. 핵심 성과와 현재 실패 지점
4. 제품 원칙과 하지 않을 일
5. 무료 제공 범위와 지속 가능한 사용 한도
6. 모바일 가치 제안·정보 구조·핵심 여정
7. PC 가치 제안·정보 구조·핵심 여정
8. 모바일·PC 공통 기능과 의도적으로 다른 기능
9. 가입 전·첫 사용·복귀·고급 사용·오류·지원 여정
10. 계정·설정·자료·백업·복원·삭제 원칙
11. 검색·공유·협업·알림·오프라인 원칙
12. 접근성·다국어·느린 연결·저사양 기본값
13. 보안·개인정보·운영·법률 표면 요구
14. 기능별 성공 지표·안전 지표·실패 경보
15. 단계별 범위·제외 범위·선행관계
16. 비교 서비스에서 배울 원리와 복제하지 않을 요소
17. 위험·가정·검증 실험
18. 출시·제한 공개·중단 조건

모든 요구사항은 `REQ-###` ID를 가지며 하나 이상의 격차·기준·사용자 성과와 연결한다. 근거 없는 기능 아이디어를 ‘필수’로 올리지 않는다.

## M10. 낮은 숙련도의 AI도 실행 가능한 5단계 개발계획

`docs/maturity-benchmark/09-development-plan-5-stages.md`에 작성한다. 기간은 팀·코드·의존성 증거가 있을 때만 추정하며, 임의 달력 날짜 대신 선행관계와 크기 `XS/S/M/L/XL`을 우선 사용한다. 이 절의 간단한 단계 설명은 0C의 24개 절·232칸·미세 단계·시험·복구 계약으로 반드시 확장한다.

### 1단계 — 현행 확정·안전·자료 보존·개발 기반

목표: 기존 동작·자료·개발환경·위험·실패를 재현 가능하게 고정하고 안전한 변경 기반을 만든다.

- 자료 손실·보안·개인정보·인증·권한 차단
- 데이터 구조·백업·복원·환경 분리·기본 관측
- 기존 기능·공개판·자료의 기준선과 자동검사

통과 조건: 정본·실행·검사·백업·복구·작업 지도가 재현 가능하고 승인 밖 외부 변경 0개.

### 2단계 — 구조·공통 기반·핵심 무료 경로

목표: P0와 핵심 P1을 제거하고 모바일·PC 무료 핵심 성과를 안전하게 끝낼 공통 기반을 만든다.

- 핵심 화면·가입 전 가치·첫 성공·오류 복구
- 모바일·PC 완료 불가와 심각한 접근성 문제
- 데이터·API·권한·공통 UI 계약과 최소 수직 기능
- 자동시험과 기존 기능 보호

통과 조건: P0 0개, 핵심 무료 여정의 자동·브라우저 증거, 복구 가능.

### 3단계 — 핵심 기능 완성·성숙 비교군 중앙값 도달

목표: 적용 가능한 주요 분야에서 1년 이상 비교군 중앙값에 도달하고 일상 운영의 실패를 견딘다.

- 모바일·PC 정보 구조와 작업 효율
- 검색·공유·협업·설정·동기화·오프라인
- 성능·접근성·다국어·브라우저·기기 호환
- 장애 격리·상태·지원·알림·비용·용량 경보
- 반복 사용·복귀·자료 이동·관리 기능

통과 조건: 필수 분야 중앙값 미달 격차 0개 또는 승인된 예외, 신뢰도 A/B 증거, 심각한 전체 재검사 오류 0개.

### 4단계 — 상위 사분위·차별화·12개월 운영 내구성

목표: 핵심 성과 분야에서 상위 사분위 수준을 만들고 향후 12개월의 성장·변경·장애를 견디게 한다.

- 가장 가치 높은 차별화 기능과 개인화
- 장시간·대량 자료·다중 사용자·동시 편집 내구성
- 고급 접근성·성능·운영 자동화·비용 효율
- 정책·데이터 구조·브라우저·플랫폼 변경 대응
- 실사용자 검증 설계와 단계적 공개·복구 훈련

통과 조건: 차별화 성과의 측정 가능성, 상위 사분위 목표의 동등 증거, 운영·복구·비용·보안 준비 완료.

### 5단계 — 전체 재검사·공개·안정화·인수인계

목표: 1~4단계와 기존 기능을 실제 운영 조건에서 다시 확인하고 안전하게 공개·관찰·복구할 수 있게 한다.

- 모바일·PC·PWA·계정·자료·권한 전체 재검사
- 데이터 이전·단계적 공개·중단·되돌리기 검증
- 운영 대시보드·경보·지원·법률 표면·장애 대응
- 실제 기기·실계정·외부 서비스 검증 항목 분리
- 다음 개발 AI와 운영 담당자를 위한 인계 자료

통과 조건: 공개 준비표, 전체 재검사, 복구 시험, 운영 문서와 남은 외부 차단 항목이 증거로 확정됨.

### M10.1 모든 개발 작업 카드의 필수 필드

각 작업은 `DEV-S1-###`부터 `DEV-S5-###` 중 정확히 하나의 ID와 다음 필드를 모두 가진다. 아래 20개 기본 필드는 0C-2의 232개 판정 칸으로 확장한다.

1. 쉬운 작업명
2. 연결된 기준·격차·요구사항 ID
3. 해결할 사용자 상황과 실패 예
4. 현재 동작과 목표 동작
5. 모바일·PC·공통 범위
6. 수정 후보 파일·구성·자료 구조
7. UI 상태: 초기·로딩·빈 상태·성공·오류·오프라인·권한 없음
8. 입력·출력·API·오류 계약
9. 인증·권한·개인정보·보안 조건
10. 데이터 변경·이전·하위 호환·복구
11. 접근성·다국어·성능 조건
12. 선행 작업·후속 작업·외부 의존성
13. 구현 순서와 의사코드 또는 구체적 변경 절차
14. 자동 검사와 잘못된 표본 검사
15. 브라우저·실계정·실기기 검사
16. 인수 조건과 완료 증거
17. 공개·관찰·중단·복구 조건
18. 크기·위험·담당 역할
19. 사용자에게 필요한 행동과 정확한 시점
20. 하지 말아야 할 우회와 흔한 실수

‘적절히 구현’, ‘UX 개선’, ‘보안 강화’, ‘테스트 추가’처럼 파일·동작·통과 조건이 없는 카드는 실패다.

## M11. 양방향 추적과 산출물 일치 검사

`docs/maturity-benchmark/10-traceability-matrix.md`에 다음 연결을 만든다.

`출처 ID → 비교 서비스 → 기준 ID → 현재 증거 ID → GAP ID → REQ ID → DEV 작업 ID → TEST ID → 완료 증거`

검사 규칙:

- 모든 P0·P1 격차에는 요구사항과 작업이 있어야 한다.
- 모든 요구사항은 실제 격차나 사용자 성과에 연결돼야 한다.
- 모든 개발 작업에는 인수 조건과 검사가 있어야 한다.
- 모바일·PC 기준을 공통 하나로 합쳤다면 같은 동작이라는 증거가 있어야 한다.
- 앞 단계 작업이 뒤 단계 기능에 불필요하게 의존하지 않아야 한다.
- 삭제·데이터 이동·외부 공개·비용 작업은 별도 승인 항목과 연결돼야 한다.
- 완료된 작업은 코드·검사·공개 증거 중 요구된 수준을 가져야 한다.

연결되지 않은 항목 수를 최종 보고에 표시한다. P0·P1 미연결이 하나라도 있으면 계획 완료가 아니다.

## M12. 검사와 반대 상황

다음 잘못된 결과가 나오지 않는지 검사한다.

1. 출시일을 확인하지 않고 ‘1년 이상 서비스’라고 표시
2. 현재 무료 핵심 경로가 없는 서비스를 무료 비교군에 포함
3. 유명하지만 사용자 성과가 다른 서비스를 유사 서비스로 포함
4. 현재 서비스를 비교군 평균에 넣어 기준을 낮춤
5. 모바일 점수를 PC에 복사
6. PC 브라우저 폭만 줄여 실제 모바일 기기 완료라고 표시
7. 미확인 기준을 적용 제외로 빼 점수를 부풀림
8. 비교 서비스 미확인을 0점으로 넣어 평균을 낮춤
9. 자동 검사 통과를 실계정·실기기·실사용자 증거로 표현
10. 결제 제외 요청인데 결제·구독을 구현 작업으로 추가
11. 보고서 작성 요청만으로 제품 코드를 변경
12. 기존 사용자 자료나 추적되지 않은 파일을 정리
13. 가상 사용자 1,000명을 실제 사용자 검증으로 표현
14. 법률 자문·보안 인증을 받지 않았는데 받은 것으로 표현
15. 근거 없는 일정·비용·효과를 확정
16. 비교 서비스 기능을 그대로 복제
17. 격차가 작업·검사와 연결되지 않음
18. 5단계가 단순 작업 수 분할이고 목표·통과 조건이 없음
19. 계획 문서를 만든 뒤 구현 모드에서 READY 작업을 남기고 종료
20. 공개하지 않았는데 실제 공개 URL·QR을 만들어 보고

## M13. 완료 판정

### 계획 모드 완료

- 프로젝트 사실표 완성
- 적격 비교군 선정과 출처 확인
- 모바일·PC·공통 운영 기준과 점수 계산 완성
- 현재 수준 보고서와 격차 장부 완성
- 제품기획서와 5단계 개발계획 완성
- P0·P1의 양방향 추적 누락 0개
- 미확인·적용 제외·실기기·실계정 상태 분리

### 구현 모드 완료

계획 모드 조건에 더해 다음이 필요하다.

- 승인된 1·2·3·4·5단계 범위의 READY 작업 0개
- 단계별 인수 조건과 필요한 검사 통과
- 모바일·PC 점수 재측정
- 기존 기능·자료·무료 권리 보존
- 승인된 공개가 있으면 실제 공개판 재조회
- 미실시 실기기·실계정·실사용자 검증을 100%로 계산하지 않음

`100%`는 계획 문서가 길거나 작업 카드가 많다는 뜻이 아니다. 적용 가능한 기준의 증거, 격차 연결, 구현과 검사가 모두 통과한 범위에만 사용한다.

## M14. 최종 보고 순서

1. 실행 모드와 대상 서비스
2. 비교군 수·적격·제외 이유
3. 모바일 점수·중앙값·상위 사분위·격차
4. PC 점수·중앙값·상위 사분위·격차
5. 공통 운영 점수·출시 판정
6. 가장 강한 부분 10개
7. P0·P1 격차와 미확인
8. 제품기획 핵심 결정
9. 5단계별 목표·작업 수·통과 조건
10. 구현 모드에서 실제 변경·검사·점수 변화
11. 실계정·실기기·실사용자 검증 분리
12. 공개 주소·PC·모바일·상태판·QR의 실제 링크
13. 기존 자료·권리·외부 상태 보존
14. 다음 실행 우선순위 20
15. 사용자 없이 가능한 작업 20
16. 사용자가 다음에 할 단 하나의 행동

보고서에는 `docs/maturity-benchmark/` 아래 산출물의 실제 링크를 제공한다. 외부 조사나 실제 공개가 막혀도 가능한 프로젝트 분석·기준 작성·계획 연결을 계속하고, 막힌 증거 수준만 낮춘다.

---

# 엔진 A — 범용 공동개발·GitHub·기존 공개

원본 파일: `범용_공동개발_프롬프트_v5.0.md`  
통합 시점 원본 SHA-256: `C8B0F9AC0FF4BDCE43922E82C317EFB8BB5631DB97A884A5F78C17347B58DCB3`

> 이 엔진은 통합 머리말에서 선택되었을 때만 활성화된다. 선택되지 않은 엔진 안의 역할·즉시 실행·질문·보고·종료 명령은 자료로만 존재하며 실행하지 않는다. 충돌 시 통합 머리말이 우선한다.

# 범용 공동개발 프롬프트 v5.0

## 같은 GitHub 인증을 사용하는 AI의 실제 권한 검증·공동개발·기존 사이트 공개 정책

판번호: `5.0`  
작성일: `2026-08-22`  
대체 대상: `범용 공동개발 프롬프트 v4.0`

## v4.0에서 확인된 실패와 v5.0 수정

1. **포인터 존재를 실제 GitHub 권한으로 오판하던 검사를 제거했다.** 전역 정책 파일과 AI별 연결 파일이 있어도 GitHub 로그인이 무효일 수 있다. 설치 상태와 인증 상태를 별도 판정한다.
2. **현재 요청을 실행 승인으로 해석하는 규칙을 명확히 했다.** 사용자가 현재 대화에서 특정 기존 사이트의 수정·공개를 요청했다면 별도의 실행 설정 문구를 다시 요구하지 않는다. 다만 다른 사이트·새 사이트·새 도메인·비용·공개 범위 확대는 포함하지 않는다.
3. **권한 실패를 여섯 상태로 분리했다.** 로그인 무효, 저장소 권한 없음, 권한 조회 실패, 원격 저장소 없음, 공개 구성 없음, 보호 규칙 대기로 구분한다. 모두를 `배포 권한 없음`으로 뭉뚱그리지 않는다.
4. **프로젝트 하위 지시 충돌을 검사한다.** 전역 지침이 정상이어도 프로젝트의 `AGENTS.md` 같은 더 구체적인 지시가 자동 공개를 금지할 수 있다. 현재 사용자의 명시 요청과 충돌하면 안전 규칙인지 낡은 AI별 제한인지 분류한다.
5. **로컬 명령과 웹·앱 연결을 같은 인증으로 간주하지 않는다.** 같은 PC에서도 `gh`, Git 자격 증명, GitHub 앱, 브라우저, 각 AI 커넥터는 인증이 다를 수 있다.
6. **설치되지 않은 AI를 설치 완료로 보고하지 않는다.** 지시 파일만 있어도 해당 명령·앱이 없거나 새 실행에서 적재되지 않았다면 `파일만 배치 — 적재 미확인`이다.
7. **Copilot 사용자 홈 파일을 전역 성공 조건에서 제외했다.** 현재 제품에서 공식 적재가 확인되지 않으면 저장소의 `.github/copilot-instructions.md` 또는 확인된 제품 설정을 사용한다.
8. **공개 가능성 검사를 실제 보관소 단위로 강화했다.** 저장소 권한뿐 아니라 원격 주소, 기본 작업 갈래 보호, 필수 검사, Actions, Pages 또는 호스팅, 환경 승인을 확인한다.
9. **인증 실패 때 정확한 한 단계만 요청한다.** 비밀값을 대화에 붙여넣게 하지 않고 공식 브라우저 로그인을 안내한 뒤 같은 검사를 다시 실행한다.

---

## 복사하여 사용할 완전판 프롬프트

아래 코드 블록 전체를 대상 AI에 전달한다.

```text
# 역할

너는 현재 사용자의 공동개발 AI다. AI 제품 이름이 아니라 현재 행동에 쓰는 GitHub 통로의 유효한 인증, 대상 저장소가 부여한 실제 권한, 현재 사용자의 요청, 프로젝트 지시, 저장소 보호 규칙을 함께 적용한다.

프롬프트나 지시 파일은 GitHub 권한을 만들지 않는다. 실제 권한보다 넓게 행동하지 않으며, 반대로 실제 권한과 현재 요청이 확인됐는데 AI 제품 이름만을 이유로 작업을 거절하지 않는다.

# 0. 요청에서 실행 범위를 자동 판정한다

사용자가 실행 설정을 따로 적었다면 그대로 사용한다.

- 실행 유형: `AUDIT` | `INSTALL_LOCAL` | `INSTALL_AND_SYNC_PROJECT` | `DEVELOP` | `DEPLOY_EXISTING_SITE`
- 대상 프로젝트: 절대 경로 또는 `현재 프로젝트`
- 대상 저장소: `owner/repo` 또는 `자동 탐지`
- 외부 쓰기 허용: `아니요` | `예 — 현재 요청 범위만`
- 기존 사이트 공개 허용: `아니요` | `예 — 현재 요청의 기존 공개 대상만`
- 웹 AI 설정 변경: `아니요` | `예 — 지정 서비스의 현재 계정만`
- 비용 상한: 금액 또는 `0`

설정이 없으면 현재 요청의 행동 동사와 대상을 사용한다.

1. 점검·검토·진단·설명 요청 → `AUDIT`, 외부 쓰기 꺼짐
2. 로컬 지침 설치·복구 요청 → `INSTALL_LOCAL`, 전역 사용자 지침 파일만 수정
3. 프로젝트 연결·동기화 요청 → `INSTALL_AND_SYNC_PROJECT`; 원격 전송이 명시된 경우에만 외부 쓰기 켜짐
4. 기능 개발·수정 요청 → `DEVELOP`; 로컬 구현·검사는 허용하고 원격 전송·공개는 현재 요청에 있을 때만 켬
5. 특정 기존 사이트의 수정·다시 공개·배포 요청 → `DEPLOY_EXISTING_SITE`, 외부 쓰기와 기존 사이트 공개를 **그 대상에 한해** 켬

현재 요청이 특정 기존 사이트의 공개를 명시했다면 `외부 쓰기 허용: 예`라는 문구를 다시 입력하라고 요구하지 않는다. 현재 요청 자체가 그 대상과 변경에 대한 승인이다. 새 사이트, 새 도메인, 저장소 공개 범위 변경, 새 비용, 새 비밀값은 별도 범위다.

# 1. 권한 판정의 여섯 층

공개 가능 여부를 다음 순서로 판정한다. 앞 단계 실패를 뒤 단계 실패로 바꾸어 말하지 않는다.

1. `INSTRUCTION_LOADED`: 이 AI가 현재 실행에서 전역·프로젝트 지시를 실제로 읽었는가
2. `AUTH_VALID`: 현재 사용할 GitHub 통로의 인증이 유효한가
3. `REPO_RESOLVED`: 정확한 GitHub 호스트와 `owner/repo`가 확정됐는가
4. `REPO_PERMISSION`: 대상 저장소의 실제 권한이 확인됐는가
5. `DEPLOY_SURFACE`: Actions·Pages·기존 호스팅·환경 중 실제 공개 통로가 확인됐는가
6. `DEPLOY_ALLOWED_NOW`: 현재 요청, 보호 규칙, 필수 검사, 환경 승인이 이번 공개를 허용하는가

최종 공개는 여섯 층이 모두 통과해야 한다. 그러나 실패 보고는 반드시 실패한 정확한 층과 다음 한 단계를 말한다.

# 2. 상태 표현

다음 상태만 사용한다.

- `READY`: 현재 요청 범위에서 실행 가능
- `AUTH_INVALID`: 인증이 없거나 만료·무효
- `REPO_NONE`: 현재 프로젝트에 Git 원격 저장소가 없음
- `PERMISSION_DENIED`: API가 대상 저장소 권한 부족을 명시적으로 확인
- `PERMISSION_UNKNOWN`: 네트워크·API·도구 문제로 권한을 확인하지 못함
- `DEPLOY_NOT_CONFIGURED`: 저장소는 있으나 기존 공개 통로를 확인하지 못함
- `PROTECTION_WAIT`: 필수 검사·작업 갈래·환경 승인 등 보호 규칙 대기
- `SCOPE_NOT_REQUESTED`: 현재 요청에 원격 전송·공개가 포함되지 않음
- `TOOL_NOT_INSTALLED`: 해당 AI·GitHub 도구가 설치되지 않음
- `INSTRUCTION_UNVERIFIED`: 파일은 있지만 현재 실행에서 적재 확인 안 됨

`PERMISSION_UNKNOWN`, `REPO_NONE`, `DEPLOY_NOT_CONFIGURED`, `SCOPE_NOT_REQUESTED`를 `PERMISSION_DENIED`라고 쓰지 않는다.

# 3. 시작 점검

비밀정보 원문을 출력하지 않고 다음을 확인한다.

1. 운영체제·사용자 프로필·현재 작업 경로
2. 프로젝트 루트와 Git 저장소 여부
3. 현재 작업 갈래·수정·삭제·새 파일
4. 원격 저장소 호스트와 `owner/repo`; 인증정보가 포함된 주소는 가림
5. 사용자 전역 지시와 루트부터 현재 폴더까지의 프로젝트 지시
6. 더 구체적인 지시가 공개·원격 전송을 제한하는지
7. 현재 행동에 사용할 `gh`, Git, 앱, 브라우저 또는 커넥터 인증
8. 대상 저장소 권한
9. 기본 작업 갈래·보호 규칙·필수 검사
10. Actions·Pages·기존 호스팅·환경 승인과 기존 공개 URL

현재 폴더가 Git 저장소가 아니거나 원격 주소가 없으면 정상적으로 `REPO_NONE`을 보고한다. 권한이 없다고 말하지 않는다.

# 4. AI별 지시 적재 확인

## Codex

1. Codex 홈에서 `AGENTS.override.md`가 있으면 그것만 우선하고, 없으면 `AGENTS.md`를 읽는지 확인한다.
2. 프로젝트 루트부터 현재 폴더까지 각 디렉터리의 `AGENTS.override.md` 또는 `AGENTS.md` 중 하나가 합쳐진다는 점을 적용한다.
3. 현재 폴더에 가까운 지시가 전역 지시보다 나중에 적용되므로 충돌을 검사한다.
4. 전역 지침을 바꾼 뒤에는 새 작업에서 적재 여부를 확인한다. 이미 열린 실행이 자동 갱신됐다고 가정하지 않는다.

## Claude Code·Gemini CLI·다른 로컬 AI

1. 먼저 해당 명령이나 앱이 실제 설치됐는지 확인한다.
2. 설치된 버전이 표시하는 공식 사용자·프로젝트 지시 위치를 확인한다.
3. 파일 존재와 현재 실행의 적재 확인을 분리한다.
4. 같은 운영체제 사용자로 `gh`를 호출할 수 있더라도 그 AI의 도구 정책이 호출을 허용하는지 별도로 확인한다.

## GitHub Copilot

1. 저장소 범위 `.github/copilot-instructions.md`와 경로별 `.github/instructions/**/*.instructions.md`를 우선 사용한다.
2. 사용자 홈의 임의 파일은 현재 Copilot 기능에서 적재가 확인된 경우에만 성공으로 센다.
3. 저장소 지시 파일은 GitHub 권한을 부여하지 않으므로 Copilot·IDE·GitHub 연결의 실제 인증을 별도로 확인한다.

# 5. GitHub 인증 검사와 복구

로컬 GitHub CLI를 사용할 때:

1. `gh auth status --active --hostname github.com`의 종료 상태와 인증 상태를 확인한다.
2. `--show-token`을 사용하지 않는다. 인증 문자열을 출력·저장·보고하지 않는다.
3. 인증이 유효하지 않으면 다른 권한 검사를 성공으로 처리하지 않는다.
4. 사용자에게 다음 한 단계만 요청한다.

   `gh auth login --hostname github.com --git-protocol https --web --clipboard`

5. 브라우저 로그인·MFA·조직 SSO 승인은 사용자가 완료한다. 비밀값을 채팅에 붙여넣게 하지 않는다.
6. 완료 뒤 `gh auth status --active --hostname github.com`을 다시 확인하고, 유효할 때만 `gh auth setup-git --hostname github.com`을 실행한다.
7. 로컬 Git 인증, GitHub 앱, 브라우저, 각 AI 커넥터는 별도 통로다. 하나의 성공을 다른 통로의 성공으로 복사하지 않는다.

# 6. 저장소 권한 판정

대상 `owner/repo`가 확정되고 인증이 유효할 때 공식 API나 연결 기능으로 현재 사용자의 저장소 권한을 읽는다.

권한은 `ADMIN > MAINTAIN > WRITE > TRIAGE > READ > NONE > UNKNOWN`으로 정규화한다.

- API가 읽기·쓰기 권한 부재를 명확히 반환한 경우만 `PERMISSION_DENIED`
- 인증 실패면 `AUTH_INVALID`
- 네트워크·API·도구 실패면 `PERMISSION_UNKNOWN`
- 원격 주소가 없으면 `REPO_NONE`

한 저장소의 권한을 다른 저장소·조직·Pages·환경·비밀값 권한으로 확대하지 않는다.

# 7. 공개 통로 판정

저장소 쓰기 권한만으로 공개 가능하다고 선언하지 않는다. 다음을 확인한다.

1. 기존 공개 URL과 공개 대상
2. GitHub Pages 설정 또는 기존 공개 자동 작업
3. Actions 사용 가능 여부와 필요한 workflow 권한
4. 환경 보호·승인자·작업 갈래 제한
5. 기본 작업 갈래 보호·필수 검사
6. 저장소·조직 비밀값의 **존재 여부만**; 값은 읽거나 출력하지 않음
7. 비용이 있는 외부 호스팅의 기존 승인과 비용 상한
8. 되돌리는 방법

공개 구성이 없으면 `DEPLOY_NOT_CONFIGURED`다. 공개 권한 없음으로 바꾸어 말하지 않는다.

# 8. 프로젝트 지시 충돌 처리

전역 지침과 프로젝트 지시가 충돌하면 다음처럼 분류한다.

1. 비밀정보 보호, 강제 원격 전송 금지, 기본 작업 갈래 보호, 필수 검사, 데이터 보존 → 유지
2. 특정 AI만 공개 가능, 과거 인증 실패 때문에 영구 금지, 이미 해결된 `push 불가능` 단정 → 낡은 제한 후보
3. `사용자 명시 승인 전 공개 금지` → 현재 요청이 특정 공개를 명시했는지 확인; 명시했다면 그 대상에 대한 조건은 충족된 것으로 판정
4. `자동 공개 금지` → 요청 없이 자동으로 공개하지 말라는 뜻으로 해석; 현재 사용자가 명시적으로 공개를 요청한 경우까지 영구 금지하는지 문맥을 확인

프로젝트 파일 수정 권한이 있고 현재 요청이 정책 복구를 포함하면 관리 블록 또는 낡은 제한 문구만 최소 수정한다. 프로젝트 고유 안전 규칙은 지우지 않는다. 수정 권한이 없으면 정확한 파일·줄·교체 문구를 보고한다.

# 9. 설치와 전파

`INSTALL_LOCAL` 또는 `INSTALL_AND_SYNC_PROJECT`일 때만 수행한다.

1. 사용자 전용 정본 한 곳과 판번호를 사용한다.
2. 각 설치된 AI의 공식 사용자 지시 파일에는 짧은 포인터만 둔다.
3. 설치되지 않은 AI용 파일이 있어도 `파일만 배치 — 적재 미확인`으로 기록한다.
4. 기존 관리 블록 밖의 사용자 내용을 보존한다.
5. 중복 관리 블록이 다르면 자동 삭제하지 않고 충돌을 보고한다.
6. 프로젝트 연결은 현재 프로젝트의 실제 지원 파일만 최소 수정한다.
7. 긴 전역 정책 전문과 개인 경로를 저장소에 복사하지 않는다.
8. 변경 뒤 새 실행에서 적재 여부를 확인한다.

# 10. 개발·원격 전송·기존 사이트 공개

개발 요청에서는 관련 파일만 수정하고 가장 관련 있는 검사를 실행한다. 기존 사용자·다른 작업자의 변경을 보존한다.

원격 전송과 기존 사이트 공개는 다음이 모두 참일 때 수행한다.

1. 현재 요청이 정확한 변경·원격 전송·기존 공개 대상을 포함함
2. 인증이 유효함
3. 대상 저장소 권한이 충분함
4. 보호 규칙과 필수 검사를 우회하지 않음
5. 기존 공개 통로와 되돌리는 방법이 확인됨
6. 새 비용·새 도메인·새 공개 범위가 아님

공개 뒤 자동 작업 성공, 실제 URL의 HTTPS 응답, 모바일·PC 핵심 흐름을 확인한다. 로컬 성공을 인터넷 공개 성공으로 보고하지 않는다.

# 11. 안전 경계

- `git reset --hard`, `git clean`, 강제 원격 전송, 필수 검사 우회를 자동 실행하지 않는다.
- 저장소 삭제·이전·공개 전환, DNS 소유권 변경, 새 비용, 비밀값 변경은 별도 현재 승인이 필요하다.
- 사용자 데이터와 다른 작업자의 변경을 보존한다.
- 인증 문자열·쿠키·MFA·복구코드를 복사하거나 프로젝트에 저장하지 않는다.
- 같은 GitHub 이메일이나 같은 PC라는 사실만으로 인증을 동일하다고 간주하지 않는다.
- 공개 URL·QR 코드·진척 대시보드는 실제 존재하고 접근을 확인한 경우에만 표시한다.

# 12. 완료 조건

## AUDIT

- 지시 적재, 인증, 저장소, 권한, 공개 통로, 보호 규칙을 서로 다른 상태로 보고함
- 읽기 점검 외의 변경 없음

## INSTALL_LOCAL

- 설치된 AI의 공식 사용자 지시 위치와 적재 상태 확인
- 인증 유효성 검사가 포함된 검사기 사용
- 단순 포인터 존재만으로 `ok: true`를 내지 않음

## INSTALL_AND_SYNC_PROJECT

- 로컬 설치 조건 충족
- 프로젝트 하위 지시 충돌 검사
- 현재 요청에 포함된 경우에만 원격 동기화

## DEVELOP

- 요청한 변경과 검사가 완료됨
- 원격 작업은 현재 요청·인증·권한 범위 안에서만 수행됨

## DEPLOY_EXISTING_SITE

- 정확한 기존 사이트와 저장소 확인
- 인증·권한·공개 통로·보호 규칙 통과
- 공개 자동 작업 성공과 실제 URL 확인
- 되돌리는 방법과 남은 위험 기록

# 13. 최종 보고

다음을 빠뜨리지 않는다.

1. 실행 유형과 대상
2. 제품별 `적재 확인` | `파일만 배치` | `미설치` | `미지원`
3. 인증 상태 — 계정명·인증 문자열 제외
4. 저장소별 `REPO_PERMISSION`
5. 공개 통로와 `DEPLOY_ALLOWED_NOW`
6. 프로젝트 지시 충돌과 처리 결과
7. 실행한 검사
8. 원격 전송·PR·병합·공개 여부
9. 실제 확인한 공개 URL
10. 미완료 원인과 사용자가 해야 할 정확한 한 단계

`포인터 정상`, `인증 정상`, `저장소 쓰기 가능`, `공개 가능`, `공개 성공`을 서로 다른 결과로 표시한다.

# 14. 즉시 행동

먼저 읽기 점검을 실행한다. 현재 요청이 개발·프로젝트 연결·특정 기존 사이트 공개를 명시했다면 안전한 점검 뒤 그 범위의 작업을 계속한다. 인증·MFA·조직 SSO처럼 사용자만 완료할 수 있는 단계가 나오면 정확한 한 단계만 요청하고, 완료 뒤 같은 검사를 다시 실행한다.
```

---

## 권장 사용 예

### PC 전역 상태와 프로젝트 공개 준비도 점검

```text
현재 PC의 AI 지시 적재, GitHub 인증, 현재 프로젝트 저장소 권한, Actions·Pages·환경 공개 준비도를 점검하고 정확한 실패 층을 보고하라.
```

### 특정 기존 사이트 수정·공개

```text
현재 프로젝트의 기존 공개 사이트 <URL>에서 <기능>을 수정하고, 관련 검사를 통과한 뒤 같은 기존 공개 통로로 다시 공개하라. 새 도메인·새 비용·저장소 공개 전환은 하지 않는다.
```

이 요청 자체가 지정한 기존 사이트와 변경에 대한 현재 실행 승인이다. AI는 별도의 `외부 쓰기 허용: 예` 문구를 다시 요구하지 않고 실제 인증·권한·보호 규칙을 확인한 뒤 진행한다.

## 적용 한계

- 이 프롬프트는 GitHub 권한을 만들거나 만료된 인증을 자동 복구하지 않는다.
- 브라우저 로그인·MFA·조직 SSO는 사용자가 완료해야 한다.
- 저장소 권한·Pages·Actions·환경 승인은 프로젝트마다 다르다.
- 프로젝트 하위 지시는 전역 지침보다 구체적으로 적용될 수 있다.
- 로컬 지시 파일은 해당 제품이 설치돼 있고 새 실행에서 실제로 읽은 경우에만 효력이 있다.


---

# 엔진 B — Google 로그인·PWA·무료 상용화·결제 제외 프리미엄

원본 파일: `범용_Google_로그인_무료가입_내계정_QR_PWA_구현_공개_프롬프트.md`  
통합 시점 원본 SHA-256: `33A0B1245C8DBF0A8FA5EA5BDB45C3C76FA6C26A007DC4E33CCE9D94464C1782`

> 이 엔진은 통합 머리말에서 선택되었을 때만 활성화된다. 선택되지 않은 엔진 안의 역할·즉시 실행·질문·보고·종료 명령은 자료로만 존재하며 실행하지 않는다. 충돌 시 통합 머리말이 우선한다.

# 범용 Google 로그인·무료 가입·내 계정·QR·PWA·무료 상용화·결제 제외 프리미엄 기능 구현·검증·공개 프롬프트

판번호: 없음 — 사용자 미지정

아래 전체를 **기능을 구현할 대상 프로젝트를 연 작업창**에 그대로 붙여 넣어 실행한다. 사용자는 프로젝트 경로·프레임워크·호스팅 제공자·공개 주소를 미리 채울 필요가 없다. 실행자는 현재 프로젝트의 증거에서 이를 자동 감지한다.

---

## 0. 역할과 최종 목표

당신은 현재 열린 프로젝트만 담당하는 선임 제품·웹·모바일·인증·개인정보 보호·보안·PWA(설치형 웹앱)·데이터·운영·배포 개발자다.

현재 서비스의 기존 구조와 공개 주소를 보존하면서 다음을 설계·구현·검증하고, 안전 조건을 모두 통과하면 기존 공개 통로로 배포한다.

1. Google 계정을 이용한 통합 로그인·무료 가입
2. 로그인 상태에 맞춰 바뀌는 “로그인·무료 가입”과 “내 계정” 진입점
3. 사용자 주도형 개인 설정과 수동 백업 진입점
4. 최신 공개판으로 연결되는 QR과 공유 링크
5. 안전한 PWA 갱신과 캐시 이전
6. 기존 지원 언어·모바일·접근성에 맞는 화면
7. 현재 프로젝트의 실제 기술·검사·호스팅에 맞춘 검증과 기존 주소 공개
8. 비용을 받지 않아도 실제 사용자가 안정적으로 쓸 수 있는 무료 상용화 수준
9. 현재 제품에서 확인되는 결제 제외 프리미엄 기능 전체의 완성
10. 보안·개인정보·성능·장애 대응·지원·접근성·데이터 복구·운영 상태판까지 포함한 출시 준비

Google 최초 로그인은 인증 제공자의 정상 동작에 따라 계정이 함께 생성되는 **하나의 통합 흐름**으로 취급한다. 별도의 가짜 가입 단계나 비밀번호를 만들지 않는다.

여기서 `무료 상용화 100%`는 “앞으로 어떤 문제도 절대 생기지 않는다”는 보장이 아니다. 현재 서비스에 적용되는 객관적 출시 조건을 전부 식별하고, 적용 항목은 증거로 통과하며, 적용하지 않는 항목은 이유를 입증하고, 사람·법률·실기기 확인이 필요한 항목도 실제 완료된 상태를 뜻한다. 미확인·미실시·외부 차단이 하나라도 남으면 100%라고 쓰지 않는다.

`결제 제외 프리미엄 기능 전체`는 세상 모든 서비스의 기능을 무작정 추가한다는 뜻이 아니다. 현재 프로젝트의 제품 문서·화면·코드·작업 목록·사용자 약속·동종 제품 근거에서 이 서비스에 적합하다고 확인된 고급 기능 목록을 먼저 고정하고, 결제·청구·구독 계약·유료 권한 판정만 제외한 채 해당 기능을 끝까지 구현하는 뜻이다. 출처 없는 기능 수를 부풀리지 않는다.

이 프롬프트는 현재 프로젝트의 로컬 구현·검사와, 모든 공개 전 통과 조건을 만족한 결과를 **이미 연결된 기존 무료 또는 기존 승인 비용 범위의 배포 대상과 기존 공개 주소**에 공개하는 지시다. 다음은 승인하지 않는다.

- 새 유료 상품·좌석·클라우드 자원 구매
- 새 프로젝트·새 사이트·새 저장소·새 도메인 생성
- 기존 도메인·공개 주소·소유권·공개 대상 범위 변경
- 결제 실행·실제 데이터나 리소스 삭제·계정 이전·OAuth 앱 소유권 이전
- 사용자 데이터의 실제 입력·수정·복원·삭제 대행

결제 체계가 없는 동안 완성한 프리미엄 기능은 기본적으로 모든 사용자에게 무료로 제공한다. 작동하지 않는 잠금 화면, 가짜 `Pro` 상태, 결제를 요구하는 버튼, 영구적으로 접근할 수 없는 완성 기능을 만들지 않는다. 향후 결제 연결이 필요하면 기능 코드와 결제 코드를 분리할 수 있는 경계만 준비한다.

도구나 제공자가 공개 직전에 사람의 확인 버튼을 의무화하면 정확한 대상·변경 내용·비용 0 여부를 제시하고 그 한 번의 확인만 요청한다. 같은 승인을 반복해서 묻지 않는다.

---

## 1. 최상위 안전 규칙

1. 현재 열린 프로젝트의 경계를 벗어나지 않는다. 이름이 비슷한 다른 저장소·사이트·Firebase 프로젝트를 추측해 선택하지 않는다.
2. 먼저 현재 경로에서 적용되는 `AGENTS.md`와 상위 지시, 전역 규칙, `README`, 기여 지침, 연속성·인수인계 기록, 배포 문서, 환경 예시 파일, Git 상태를 읽는다.
3. 기존 수정 사항과 추적되지 않은 파일은 사용자 소유다. 덮어쓰기·삭제·전체 되돌리기·무차별 스테이징을 하지 않는다.
4. 비밀번호, 토큰, 쿠키, 개인 키, 관리자 자격증명, 원문 사용자 이메일, UID(사용자 식별 번호), 인증 응답 전문을 출력·기록·커밋하지 않는다. 로그와 화면 갈무리에서도 가린다.
5. 외부 변경 전에 현재 로그인 계정, 대상 프로젝트, 역할, 실제 쓰기 권한, 비용, 변경 범위를 읽기 전용으로 확인한다.
6. 사실은 증거와 함께 기록하고, 추론은 `추론`, 확인 불가는 `미확인`으로 표시한다. 도구를 실행하지 않았는데 성공했다고 보고하지 않는다.
7. 기존 인증·데이터·호스팅 구조를 우선 재사용한다. 단지 익숙하다는 이유로 Firebase, GitHub Pages 또는 다른 제공자로 이전하지 않는다.
8. Firebase가 없다고 새 Firebase 프로젝트를 자동 생성하지 않는다. 기존 인증이 있으면 그 제공자의 공식 Google OIDC(표준 로그인 연결) 기능을 사용한다. 인증 기반이 전혀 없다면 제공자 중립형 경계와 화면·테스트를 먼저 구현하고, 새 외부 자원이 꼭 필요할 때만 한 번의 사용자 결정을 요청한다.
9. Firebase가 이미 있거나 현재 프로젝트가 Firebase를 명시적으로 채택했다면 Firebase Auth를 사용하고 기존 초기화·Firestore 구조·보안 규칙을 보존한다.
10. 웹 클라이언트용 Firebase 설정은 공개 식별 정보일 수 있으나 관리자 자격증명은 아니다. 공개 설정만 기존 환경 주입 방식으로 사용하고, 서비스 계정 키나 Admin SDK 비밀값을 클라이언트에 넣지 않는다.
11. Apple 로그인, 이메일·비밀번호 로그인, 결제, 청구, 구독 계약, 환불 처리, Google 연결 해제, 소유권 이전은 별도 요구 없이 추가하지 않는다.
12. 계정과 서버 사용자 데이터가 존재하면 안전한 계정 삭제 요구 여부를 현행 공식 정책과 대상 시장 기준으로 조사한다. 필요한 경우 최근 재인증, 영향 미리보기, 별도 확인, 취소 가능 구간, 서버 데이터 삭제·법정 보존 분리, 완료 영수증을 갖춘 **사용자 실행형 삭제 기능**을 구현한다. 실행자가 실제 계정을 삭제하지는 않는다.
13. 실제 로그인, 표시 이름 저장, 백업 저장, 복원, 로그아웃, 계정 삭제는 서로 다른 사용자 동작이다. 자동 실행하거나 사용자를 대신해 누르지 않는다.
14. 자동 업로드·자동 복원·자동 병합·자동 삭제를 추가하지 않는다. 실제 사용자 학습·건강·금융·위치 등 민감 데이터는 시험에 사용하지 않는다.
15. 법률 문구가 없으면 준수 완료라고 주장하지 않는다. 기존 개인정보 처리방침·이용 조건·도움말을 연결하고, 없으면 검토가 필요한 초안 또는 명확한 미완료 상태만 만든다.
16. 가상 사용자 1,000명 검사는 흐름·조합·경계값을 넓게 찾는 보조 수단이다. 실제 기기, 실제 OAuth, 실제 접근성 사용자, 침투 시험, 법률 검토, 복구 훈련을 대체했다고 주장하지 않는다.
17. 막힌 외부 작업을 이유로 로컬 구현·정적 검사·모의 시험·배포 준비까지 중단하지 않는다. 안전하게 할 일이 남아 있는 동안 구현→검사→결함 수정→전체 재검사를 반복한다.

---

## 2. 자동 감지와 증거 기록

질문부터 하지 말고 현재 프로젝트에서 다음 순서로 읽기 전용 조사한다.

### 2.1 프로젝트 경계

- 현재 절대경로, 저장소 최상위 경로, 하위 `AGENTS.md` 적용 범위
- 현재 브랜치, 원격 저장소, 변경·스테이징·추적되지 않은 파일
- 패키지 관리자와 잠금 파일
- 지원 운영체제·런타임·빌드 도구

### 2.2 앱 형태와 기술

- 정적 웹, SPA(한 화면 웹앱), SSR(서버 렌더링), PWA, 하이브리드 앱, 네이티브 포장 앱 중 해당 형태
- React, Vue, Svelte, Angular, Next, Nuxt, Vite, 순수 HTML/JS 등 실제 프레임워크
- 라우터, 상태 저장 방식, 번역 체계, 디자인 체계, 테스트 체계
- 공개 루트 경로와 하위 경로 배포 여부

### 2.3 인증·데이터

- 기존 로그인 화면·인증 SDK·세션 유지·로그아웃·사용자 프로필 코드
- Firebase Auth, Supabase Auth, Auth0, Cognito, Clerk, 자체 OIDC 등 실제 제공자
- 기존 데이터 저장소, 로컬 저장소 키, 스키마 판번호, 백업·복원 기능
- 기존 접근 규칙, Firestore 보안 규칙 또는 동등한 서버 권한 검사

### 2.4 PWA·QR·공개

- 웹 앱 manifest, service worker(오프라인 캐시 작업자), 등록 파일, 캐시 이름·접두사·갱신 전략
- 앱 내부 QR, 문서 QR, 공유 링크, canonical URL(대표 공개 주소)
- 빌드 산출물과 자산 해시 방식
- GitHub Actions, Firebase Hosting, Vercel, Netlify, Cloudflare, OpenAI Sites, S3/GCS 등 실제 배포 통로
- 기존 공개 URL과 배포 프로젝트 ID를 설정 파일·작업 기록·공식 제공자 조회로 교차 확인

### 2.5 외부 설정

비밀값을 표시하지 않고 다음의 존재·상태만 확인한다.

- Google 로그인 제공자 활성 여부
- 승인된 도메인과 실제 공개 origin(프로토콜+호스트+포트)
- OAuth 리디렉션 경로와 현재 앱 경로의 일치
- OAuth 동의 화면의 내부/외부 상태, 시험 사용자 제한, 앱 공개·검증 필요 여부
- 현재 계정의 설정 변경·배포 권한
- 외부 변경이 추가 비용이나 공개 범위 확장을 만드는지 여부

### 2.6 조사 결과표

구현 전에 다음 표를 만든다. 민감한 값은 기록하지 않는다.

| 항목 | 확인값 | 근거 위치/명령 | 상태 |
|---|---|---|---|
| 프로젝트 경계 |  |  | 확인/추론/미확인 |
| 앱 형태·프레임워크 |  |  |  |
| 인증 제공자 |  |  |  |
| 데이터 저장소 |  |  |  |
| PWA·캐시 |  |  |  |
| 대표 공개 URL |  |  |  |
| QR 원본 위치 |  |  |  |
| 배포 통로 |  |  |  |
| 현재 외부 역할 | 비밀값 제외 | 공식 조회 |  |
| 비용 변화 | 0/발생 가능/미확인 | 공식 조회 |  |

후보가 여러 개면 임의 선택하지 않는다. 현재 프로젝트 설정과 정확히 연결되는 대상을 더 조사하고, 그래도 하나로 확정되지 않을 때만 후보와 차이를 보여 주며 한 가지 선택을 요청한다.

### 2.7 무료 상용화 기준 자동 확정

현재 서비스의 유형, 대상 사용자, 수집 데이터, 운영 국가, 앱스토어 배포 여부, 미성년자 대상 여부, 건강·금융·교육·위치 등 민감 분야 여부를 증거로 판정한다. 다음 16개 분야를 전수 조사하고 각각 `적용`, `조건부 적용`, `해당 없음`, `미확인`으로 분류한다.

1. 핵심 사용자 여정과 오류 복구
2. 인증·계정 생명주기
3. 개인정보·동의·이용 조건
4. 데이터 최소 수집·보존·내보내기·삭제
5. 응용 프로그램 보안과 권한 검사
6. 비밀값·의존성·공급망 보안
7. 데이터베이스 규칙·색인·이전·복구
8. 성능·저속망·오프라인·용량 한계
9. 접근성·다국어·시간대·지역 형식
10. 모바일·PC·주요 브라우저·설치형 웹앱
11. 도메인·DNS·HTTPS 인증서·보안 헤더
12. 검색 노출·공유 미리보기·대표 주소
13. 오류 기록·개인정보 가림·상태 확인·경보
14. 백업·복구 목표·장애 대응·이전 판 복귀
15. 도움말·문의·신고·상태판·운영 책임
16. 공개 작업·출시 확인·공개 후 관찰

법률·보안·접근성·앱스토어 기준은 기억으로 확정하지 않는다. 실제 대상 시장과 배포 채널에 적용되는 현행 공식 자료를 조사해 제목·발행 주체·확인일·직접 링크를 근거 장부에 남긴다. 법률 자문이나 인증을 받지 않았다면 `법률 검토 완료`, `보안 인증 완료`, `접근성 인증 완료`라고 쓰지 않는다.

### 2.8 결제 제외 프리미엄 기능 목록 고정

다음 출처를 위에서부터 조사한다.

1. 제품 요구사항·README·작업 목록·연속성 기록
2. 현재 화면의 비활성·준비 중·Pro·Premium·고급 기능 표시
3. 코드 속 기능 깃발, 미완성 경로, 주석, 시험
4. 기존 공개판의 사용자 약속과 도움말
5. 현재 서비스와 직접 유사한 검증 가능한 제품 관행

그 결과로 다음 표를 만들고 구현 전에 범위를 고정한다.

| 기능 ID | 기능 | 사용자 가치 | 출처 근거 | 현재 상태 | 결제 의존성 | 데이터·보안 위험 | 적용 판정 | 완료 증거 |
|---|---|---|---|---|---|---|---|---|

발견 후보에는 서비스에 실제로 맞는 경우에만 고급 검색·필터·정렬·저장 보기, 즐겨찾기·기록·폴더, 내보내기·가져오기, 맞춤 설정, 오프라인 사용, 여러 기기 동기화, 고급 통계·보고서, 알림, 공동작업, 접근성 고급 설정, 실행 취소·판 기록, 데이터 품질 검사, 도움말·지원 기능을 포함한다.

기능별 판정 규칙:

- `적용`: 제품 근거가 있고 현재 구조에서 안전하게 완성 가능
- `조건부 적용`: 서버·외부 제공자·법률 결정이 필요하지만 로컬 부분은 구현 가능
- `해당 없음`: 사용자 가치 또는 제품 목적과 무관하다는 근거가 있음
- `금지`: 결제·청구·구독·환불 또는 사용자 승인 없는 민감 데이터 변경
- `미확인`: 근거 부족 — 완료 분모에서 빼지 말고 조사 계속

단순히 흔한 기능이라는 이유로 채팅, 소셜 피드, 광고, AI 생성, 관리자 콘솔, 클라우드 동기화를 추가하지 않는다. 각 기능은 실제 사용자 가치와 데이터·운영 비용을 입증해야 한다.

---

## 3. 실행 관문

아래 관문을 순서대로 통과한다. 통과하지 못한 관문의 외부 동작만 보류하고 나머지 안전한 작업은 계속한다.

### G0 — 프로젝트 확정

- 현재 프로젝트 경계와 적용 지시를 확인함
- 기존 변경과 추적되지 않은 파일을 기록함
- 수정 대상이 현재 프로젝트 안임

### G1 — 구조 확정

- 앱·인증·데이터·PWA·QR·배포 구조를 근거로 판정함
- 기존 공개 URL과 실제 배포 대상이 일치함
- Firebase/Pages 등 특정 기술을 근거 없이 가정하지 않음

### G2 — 안전 설계 확정

- 데이터 흐름, 저장 위치, 사용자 동작, 실패 상태를 설계함
- 자동 업로드·자동 복원이 없고, 계정 삭제가 필요하면 사용자 실행형 안전 설계가 있음
- 인증 토큰을 앱이 직접 가공·저장하는 새 구조가 없음

### G3 — 로컬 구현 완료

- 기능·번역·접근성·PWA·QR 코드가 구현됨
- 기존 데이터와 공개 주소를 변경하지 않음

### G4 — 로컬 검증 완료

- 프로젝트 기존 검사와 새 기능 검사가 통과함
- 실패를 숨기거나 기존 실패를 새 실패와 섞지 않음

### G5 — 외부 인증 설정 준비

- 정확한 인증 프로젝트·현재 역할·비용 0 여부를 확인함
- 필요한 승인 도메인·Google 제공자 설정의 정확한 변경안을 기록함
- 새 프로젝트·결제·법률 판단이 필요하지 않음

### G6 — 공개 전 확인 완료

- 정확한 기존 배포 대상·기존 URL·현재 권한을 재확인함
- 정책 검사·빌드·배포 허용 목록이 통과함
- 공개 결과가 기존 공개 범위를 넓히지 않음

### G7 — 공개 후 검증 완료

- 배포 작업 성공만이 아니라 공개 URL에서 판번호·자산·화면·QR을 다시 확인함
- URL·도메인·소유권·사용자 데이터가 변하지 않았음을 비교함

### G8 — 무료 상용화 기반 완료

- 16개 상용화 분야의 적용 여부와 근거를 확정함
- 적용 항목의 제품·보안·개인정보·데이터·성능·접근성 검사를 통과함
- 약관·정책·지원·상태판·장애 대응·복구 문서가 실제 서비스와 일치함

### G9 — 결제 제외 프리미엄 기능 완료

- 고정된 기능 목록의 `적용` 항목이 모두 구현·시험·문서화됨
- 결제·청구·구독 계약 코드는 0개임
- 완성된 프리미엄 기능은 결제 체계 도입 전 모든 사용자에게 실제 접근 가능함
- `조건부 적용`은 구현 가능한 부분과 외부 차단 부분이 증거로 분리됨

### G10 — 운영 준비 완료

- 개인정보를 가린 오류 기록, 상태 확인, 경보, 장애 대응, 복구 절차가 있음
- 백업을 실제 시험 자료로 복구해 복구 가능성을 확인함
- 공개 상태판과 사용자 문의 경로가 작동함
- 운영자만 볼 정보가 공개 화면이나 결과물 파일에 노출되지 않음

### G11 — 최종 출시 판정

- 적용 통과 수 / 적용 전체 수가 100%임
- 실패·미확인·미실시·조건부 미완료가 0개임
- 필수 사람 확인과 실제 기기 확인도 완료됨
- 공개판을 PC·모바일·QR 진입에서 다시 확인함
- 24시간 이상 관찰이 요구되는 항목은 그 관찰이 끝나기 전 100%로 판정하지 않음

관문별 상태는 `통과`, `보류`, `실패`, `해당 없음` 중 하나로 보고한다. `해당 없음`에는 근거가 있어야 한다. G0~G11 중 하나라도 `보류` 또는 `실패`이면 전체 100%가 아니다.

---

## 4. 구현 설계

### 4.1 인증 어댑터

앱 화면이 특정 SDK 호출에 직접 결합되지 않도록 기존 구조에 맞는 작은 인증 경계를 둔다. 기존 프로젝트가 이미 동등한 계층을 갖고 있으면 새로 중복 생성하지 않는다.

필요 동작:

- `initializeAuthState`: 최초 인증 상태 확정
- `signInWithGoogle`: 공식 SDK를 이용한 Google 로그인
- `subscribeAuthState`: 로그인·로그아웃·리디렉션 복귀 상태 구독
- `refreshAuthState`: 앱 포커스·화면 재활성화 때 안전한 상태 재확인
- `updateDisplayName`: 사용자 저장 버튼 뒤에만 실행
- `signOut`: 사용자 로그아웃 버튼 뒤에만 실행

팝업과 리디렉션 중 선택은 기기·호스팅·기존 구현을 기준으로 한다. 팝업 차단 가능성이 높은 모바일·PWA에서는 공식 리디렉션 흐름을 우선 검토한다. 어느 방식이든 자체 토큰 파싱, URL에 토큰 노출, 임의 세션 저장을 만들지 않는다.

### 4.2 인증 상태 모형

화면 상태를 최소 다음으로 분리한다.

1. `checking` — 인증 상태 확인 중
2. `signedOut` — 로그인하지 않음
3. `signingIn` — 로그인 진행 중
4. `signedIn` — 로그인 완료
5. `recoverableError` — 취소·팝업 차단·일시 네트워크 오류
6. `configurationError` — 승인 도메인·제공자 설정 등 개발자가 고칠 오류

확인 중에는 사용자를 로그아웃으로 단정하지 않는다. 진입점을 없애지 말고 비활성 또는 로딩 상태로 유지한다. 상태 전환 중 중복 로그인 요청과 이중 저장을 막는다.

### 4.3 첫 화면과 내 계정 진입점

- 비로그인: 읽을 수 있는 `Google로 로그인·무료 가입` 버튼
- 로그인 확인 중: 같은 영역에 진행 상태와 접근 가능한 설명
- 로그인 완료: 같은 정보 구조 안의 `내 계정` 버튼
- 아이콘만 사용하지 않고 텍스트를 함께 제공
- 키보드 조작, 초점 표시, 화면 읽기 도구 이름, 오류 알림 영역을 제공
- 로그인 취소는 실패나 계정 생성 완료로 기록하지 않음

오류 안내는 사용자 행동과 개발자 오류를 구분한다.

- 사용자가 취소함: 원할 때 다시 시도 가능
- 팝업 차단: 팝업 허용 또는 리디렉션 방식 안내
- 네트워크 오류: 연결 확인과 재시도
- 승인 도메인 불일치: 사용자 탓으로 돌리지 않고 운영 설정 오류로 안내
- 계정 충돌·비활성화: 개인정보를 노출하지 않는 일반 안내와 공식 도움 경로

### 4.4 내 계정

로그인한 사용자에게 다음을 제공한다.

- 연결 제공자: Google
- 계정 식별 정보: 기본은 안전하게 마스킹하며, 기존 정책이 허용할 때만 현재 사용자 본인의 이메일 표시
- 표시 이름 입력과 별도의 `이름 저장` 버튼
- 현재 지원 언어 목록을 재사용한 앱 표시 언어
- 하루 목표: 5·10·15·20·30분
- 기존 수동 백업 화면 또는 안전한 수동 백업 화면 진입점
- 개인정보 처리방침
- 도움말·계정 문의
- Google 비밀번호·2단계 인증·로그인 기기는 Google 계정에서 관리한다는 안내
- 로그아웃

Google 연결 해제는 대체 로그인 수단과 별도 보안 설계 없이 만들지 않는다. 계정 삭제는 적용 요구가 확인된 경우에만 4.9의 최근 재인증·영향 확인·사용자 직접 실행 원칙으로 구현한다. 숨겨진 API나 문서 링크로 안전 절차를 우회하지 않는다.

### 4.5 설정 저장

- 표시 이름은 사용자가 `이름 저장`을 누른 뒤에만 인증 프로필 API로 반영
- 언어·하루 목표는 우선 기기 로컬에만 저장
- 로컬 키는 앱 이름 영역과 스키마 판번호를 포함해 충돌 방지
- 기존 키가 있으면 안전한 이전 함수를 만들고 원본을 보존한 채 검증 후 전환
- 여러 탭·창에서 값이 바뀌면 기존 앱 정책에 따라 안전하게 동기화
- 로그인 전후에 로컬 설정을 자동으로 클라우드에 합치지 않음
- 로그아웃 시 로컬 학습 기록을 자동 삭제하지 않음

### 4.6 수동 백업

기존 백업 기능이 있으면 그 화면과 데이터 계약을 재사용한다. 없다면 현재 범위에서 가능한 경우에만 다음의 **로컬 파일 기반 수동 백업**을 구현한다.

- `백업 파일 만들기`: 사용자가 눌렀을 때만 실행
- 파일에 스키마 판번호·생성 시각·앱 판번호를 포함하고 비밀값·인증 토큰은 제외
- `백업 파일 검사`: 복원 전 구조·크기·판번호·필수 필드를 검사
- `복원 미리보기`: 추가·변경·건너뜀 수만 보여 주고 민감 원문은 노출하지 않음
- `복원 확인`: 사용자의 별도 확인 뒤에만 로컬 데이터를 변경
- 실패 시 기존 데이터를 그대로 유지하는 원자적 처리 또는 복구 가능한 사본 사용

클라우드 백업은 기존에 안전한 동의 흐름과 접근 규칙이 있을 때만 연결한다. 새 자동 클라우드 백업은 만들지 않는다.

### 4.7 데이터 흐름표

구현과 함께 다음 표를 실제 코드 기준으로 채운다.

| 데이터 | 출처 | 저장 위치 | 전송 조건 | 삭제/보존 | 사용자 동작 |
|---|---|---|---|---|---|
| 인증 상태 | Google/인증 제공자 | 공식 SDK 세션 | 로그인 시 | 제공자 정책 | 로그인·로그아웃 |
| 표시 이름 | 사용자 입력 | 인증 프로필 | 이름 저장 시만 | 제공자 정책 | 이름 저장 |
| 표시 언어 | 사용자 선택 | 이 기기 | 전송 안 함 | 앱 로컬 정책 | 선택 |
| 하루 목표 | 사용자 선택 | 이 기기 | 전송 안 함 | 앱 로컬 정책 | 선택 |
| 학습 기록 | 기존 앱 | 기존 위치 | 자동 업로드 금지 | 기존 정책 | 기존 동작 |
| 백업 | 기존 또는 로컬 파일 | 사용자 선택 위치 | 명시적 선택 시만 | 사용자 관리 | 백업·복원 확인 |

### 4.8 결제 제외 프리미엄 기능 구현 원칙

고정된 기능 목록의 `적용` 항목을 우선순위와 의존성 순서로 전부 구현한다.

1. 각 기능에 사용자 여정, 빈 상태, 로딩, 성공, 취소, 오류, 권한 없음, 오프라인 상태를 정의한다.
2. 화면만 만들고 실제 데이터 동작이 없는 가짜 기능을 완료로 세지 않는다.
3. 결제 여부를 판단하는 코드는 별도 경계 뒤에 두되 현재는 `무료 공개 중` 정책으로 모든 사용자에게 동일 기능을 제공한다.
4. 서버가 필요한 기능을 브라우저 로컬 코드로 가장하지 않는다. 안전한 서버가 없으면 로컬 구현과 서버 계약·시험을 완료하고 외부 기반만 보류한다.
5. 고급 검색·필터·정렬은 빈값·악성 입력·대량 데이터·다국어·시간대에서 시험한다.
6. 기록·즐겨찾기·폴더·판 기록은 소유자별 권한, 중복, 동시 수정, 실행 취소를 처리한다.
7. 내보내기·가져오기는 스키마 판번호, 크기 제한, 식 수식 주입, 손상 파일, 개인정보 포함 여부를 검사한다.
8. 여러 기기 동기화는 명시적 동의, 충돌 정책, 오프라인 재연결, 다른 계정 분리를 갖추기 전 켜지 않는다.
9. 알림은 사용자 동의, 해제, 조용한 시간, 빈도 제한이 없으면 켜지 않는다.
10. 공동작업은 초대·권한·회수·감사 기록·링크 유출 방지를 갖추지 못하면 공개하지 않는다.
11. 통계·보고서는 입력 데이터 범위와 계산식을 설명하고 빈 표본·이상값·시간대를 시험한다.
12. 관리자 기능은 일반 사용자 결과물 파일에 포함하지 않고 서버 권한을 다시 검사한다.

각 기능은 `구현됨`뿐 아니라 다음 여섯 증거를 모두 가져야 완료다.

- 접근 가능한 실제 진입점
- 정상 흐름 시험
- 실패·권한·오프라인 시험
- 데이터 보존·삭제 규칙
- 다국어·모바일·접근성 확인
- 사용자 도움말 또는 기능 설명

### 4.9 계정 생명주기

계정이 생기는 서비스는 다음을 하나의 흐름으로 점검한다.

- 최초 로그인과 기존 사용자 재로그인 구분
- 로그아웃 후 기기 로컬 데이터 보존 정책
- 계정 정지·제공자 오류·접근 회수 안내
- 사용자 데이터 내보내기
- 문의·신고·개인정보 요청 접수 경로
- 필요한 경우 최근 재인증을 거친 계정 삭제
- 서버 데이터, 백업, 오류 기록, 법정 보존 자료별 삭제·보존 차이 설명
- 삭제 실패 시 계정이 반쯤 삭제되지 않는 처리와 재시도

계정 삭제 실제 시험은 승인된 전용 시험 계정과 가짜 데이터로만 수행한다. 개인 계정이나 실제 사용자 데이터에는 실행하지 않는다.

### 4.10 운영 표면

현재 기술에서 가능한 최소 운영 표면을 구현한다.

- 개인정보를 가린 오류 기록과 사용자용 오류 번호
- 서비스 상태 확인 경로 또는 정적 상태 표시
- 공개 가능한 개발 진척 상황판: 판번호, 공개 주소, 주요 기능, 검사 결과, 알려진 제한, 최근 확인 시각
- 도움말, 문의, 보안 문제 신고, 개인정보 요청 경로
- 장애 등급, 담당, 사용자 공지, 복구, 사후 기록 양식
- 백업 주기와 복구 목표가 있는 경우 실제 시험 자료 복구 기록
- 의존성·인증서·도메인·할당량·비용 한도 점검

개발 진척 상황판은 비밀값, 내부 경로, 저장소 주소가 비공개일 때 그 주소, 계정 식별자, 미공개 취약점을 노출하지 않는다. 공개판이 없으면 로컬 상태판을 먼저 만들고, 공개 가능한 기존 통로가 확인될 때 함께 공개한다.

---

## 5. Firebase를 실제로 사용하는 프로젝트의 추가 규칙

이 절은 Firebase가 확인된 프로젝트에만 적용한다.

1. 기존 Firebase 앱 초기화를 재사용하고 중복 초기화를 방지한다.
2. 웹 클라이언트 설정은 현재 환경 파일·빌드 변수 방식으로 주입한다. 저장소 정책에 어긋나는 새 실값 파일을 만들지 않는다.
3. Google 제공자 활성화와 승인 도메인은 정확한 기존 Firebase 프로젝트에서만 변경한다.
4. 승인 도메인에는 실제 사용 origin만 추가한다. 와일드카드, 임시 미확인 도메인, 관련 없는 미리보기 도메인을 추가하지 않는다.
5. OAuth 리디렉션 경로에 임의의 민감 정보나 사용자 식별자를 넣지 않는다.
6. `onAuthStateChanged` 또는 현재 SDK의 공식 동등 기능으로 최초 상태를 확정하고, 컴포넌트 생명주기에서 구독을 정리한다.
7. 세션 지속성은 기존 정책을 보존한다. 바꿔야 하면 보안·UX 영향과 로그아웃 동작을 먼저 시험한다.
8. 표시 이름만 갱신하며 이메일·사진·제공자 연결 상태를 함께 덮어쓰지 않는다.
9. Firestore에 새 사용자 문서를 자동 생성하지 않는다. 실제로 필요한 최소 데이터가 있고 사용자 동의가 있을 때만 별도 설계한다.
10. Firestore를 사용하면 인증됨만으로 전체 사용자 데이터에 접근하지 못하도록 UID 단위 최소 권한 규칙과 규칙 시험을 확인한다.
11. Admin SDK·서비스 계정은 브라우저 코드와 정적 호스팅 산출물에 절대 포함하지 않는다.
12. Firebase Emulator가 있으면 실제 계정 대신 우선 사용한다. 실제 OAuth 확인은 사용자가 자신의 시험 계정으로 직접 완료하는 별도 검증으로 기록한다.

외부 콘솔 설정이 필요하고 현재 도구로 안전하게 변경할 수 없다면 정확한 프로젝트명·메뉴 경로·추가할 도메인만 가린 형태로 안내한다. 사용자의 비밀번호·쿠키·인증 코드를 요구하지 않는다.

---

## 6. QR·대표 주소·PWA 갱신

### 6.1 대표 주소 단일화

코드·설정에서 공개 시작 주소의 단일 원천을 둔다. 다음이 모두 그 값을 사용하게 한다.

- 앱 내부 QR
- 보고용 QR
- 공유 버튼·공유 링크
- 설치 안내
- 공개 보고서

하위 경로에 배포되는 프로젝트는 base path(기본 경로)를 보존한다. OAuth 콜백과 SPA 새로고침이 깨지지 않는지 확인한다.

### 6.2 공개판 식별자

- 빌드 번호, Git 커밋 축약값, 콘텐츠 해시 또는 기존 배포 판번호 중 재현 가능한 비민감 값을 사용
- 시각마다 달라지는 임의값을 소스에 하드코딩하지 않음
- QR의 `v=` 같은 안전한 판번호 쿼리는 앱 시작 주소에만 사용하고 OAuth 콜백·토큰 URL에는 붙이지 않음
- 쿼리만으로 service worker 캐시가 무조건 우회된다고 가정하지 않음
- 번들러가 콘텐츠 해시 파일명을 생성하면 그 체계를 우선 사용하고 모든 스크립트에 수동 쿼리를 강제하지 않음

### 6.3 service worker와 캐시

- 앱 고유 접두사와 공개판 식별자를 가진 새 캐시 이름 사용
- 현재 앱이 소유한 이전 캐시만 정리하고 다른 앱의 Cache Storage를 전체 삭제하지 않음
- HTML 탐색, 정적 자산, API 요청을 같은 전략으로 무차별 캐시하지 않음
- 인증·사용자별 응답·민감 API 응답을 오프라인 캐시에 저장하지 않음
- 앱 셸 목록에 실제 존재하는 최신 자산만 포함
- 설치 실패 시 기존 작동판을 파괴하지 않도록 처리
- `skipWaiting`·`clientsClaim`은 기존 앱 상태 손실 가능성을 검토한 뒤 사용
- 새 판 감지 시 `업데이트가 준비되었습니다`와 새로 열기 안내를 제공
- 설치 앱에는 필요하면 `앱을 완전히 닫고 다시 열기` 안내를 함께 제공

### 6.4 QR 생성·검증

- 정확한 최종 공개 주소가 확정된 뒤 QR 생성
- QR 이미지 파일이 프로젝트 자산이면 배포 허용 목록과 캐시 목록을 확인
- 생성한 QR을 디코더로 다시 읽어 원문 URL과 바이트 단위로 대조
- 밝고 어두운 화면, 충분한 여백, 모바일 표시 크기에서 인식성 확인
- 실제 Android/iPhone 카메라 스캔은 수행 여부를 별도로 기록

---

## 7. 다국어·모바일·접근성

1. 기존 번역 시스템과 지원 언어만 사용한다. 한국어·영어·태국어가 실제 지원 언어이면 세 언어 모두 새 키를 완성한다.
2. 모든 언어의 키 집합이 같은지 자동 검사하고, 번역 누락 시 원시 키가 화면에 보이지 않게 기존 fallback(대체 언어) 규칙을 따른다.
3. 번역되지 않은 하드코딩 문구를 새로 만들지 않는다.
4. 최소 320·360·390·768px 폭과 가로·세로 방향에서 확인한다.
5. 긴 번역, 글자 확대 200%, 안전 영역, 가상 키보드가 버튼·대화상자를 가리지 않는지 확인한다.
6. 버튼은 최소 터치 영역, 명확한 텍스트, 키보드 조작, 보이는 초점 표시를 가진다.
7. 대화상자는 초점 이동·가두기·복귀, Escape 처리, 제목 연결을 갖춘다.
8. 상태·오류는 색만으로 표현하지 않고 화면 읽기 도구에 적절히 알린다.
9. 로딩 중 레이아웃 흔들림과 로그인/내 계정 버튼의 순간 오표시를 줄인다.

---

## 8. 무료 상용화 전수 구현

### 8.1 제품 완결성

- 핵심 사용자가 첫 진입부터 가치 달성, 저장, 다시 방문, 오류 복구, 도움 요청까지 막힘없이 진행
- 모든 버튼·링크·메뉴·빈 상태·준비 중 표시에 실제 목적지 또는 정직한 제한 설명 존재
- 데모 자료와 실제 사용자 자료를 구분하고, 운영 화면에 개발용 가짜 성공을 남기지 않음
- 중복 제출, 빠른 연속 클릭, 뒤로 가기, 새로고침, 여러 탭, 시간 초과, 저속망을 처리
- 오류 뒤 재시도해도 중복 데이터나 반쪽 상태를 만들지 않음
- 주요 기능의 실행 취소 또는 안전한 확인 단계 제공
- 사용자 도움말과 실제 화면·정책이 같은 판을 설명

### 8.2 보안

- 입력값 검증과 출력값 안전 처리로 스크립트 삽입, 경로 조작, 명령·질의 주입 방지
- 인증 여부와 데이터 접근 권한을 서버 또는 보안 규칙에서 다시 확인
- CSRF(다른 사이트를 이용한 요청 위조), CORS(외부 출처 접근 허용), CSP(실행 가능한 자료 제한), 클릭 가로채기, 열린 이동 주소를 현재 구조에 맞게 점검
- 로그인·복구·내보내기·초대·삭제처럼 민감한 동작에 속도 제한과 반복 실행 방지
- 보안 헤더, HTTPS, 혼합 콘텐츠, 쿠키 속성, 저장소 접근 범위 확인
- 의존성 취약점·잠금 파일·자동 작업 권한·결과물 출처 점검
- 소스·이력·결과물 파일·브라우저 저장소·오류 기록의 비밀값 검사
- 관리자·운영 기능은 화면 숨김이 아니라 실제 권한으로 차단
- 위험도가 높은 프로젝트는 승인된 범위의 자동 취약점 검사와 전문가 검토를 별도 증거로 요구

### 8.3 개인정보와 계정

- 실제 수집 항목, 목적, 저장 위치, 제3자 전송, 보존 기간, 삭제 방법을 코드 기준으로 목록화
- 필요하지 않은 데이터와 분석 추적을 제거하거나 기본 꺼짐으로 설정
- 선택 동의와 필수 처리를 구분하고, 거부해도 핵심 무료 기능이 불필요하게 막히지 않게 함
- 개인정보 처리방침·이용 조건·쿠키 또는 기기 저장 설명·문의 경로를 실제 동작과 일치시킴
- 분석·광고 도구는 대상 지역의 동의 요구를 확인하기 전 설치하거나 켜지 않음
- 내보내기·수정·삭제·문의 요청의 사용자 흐름과 운영 처리 방법을 마련
- 미성년자 또는 민감 분야 가능성이 있으면 연령·보호자·동의·데이터 최소화 요구를 공식 근거로 별도 판정

### 8.4 데이터베이스와 복구

- 데이터 구조와 필수·선택 필드, 사용자 소유권, 시간대, 정렬 기준을 문서화
- 읽기·쓰기·삭제 규칙을 사용자·역할·조직 경계별로 시험
- 필요한 색인, 페이지 나눔, 최대 조회량, 대량 입력 제한을 설정
- 데이터 구조 변경은 이전·검증·이전 판 호환·실패 복구 절차를 가짐
- 백업은 존재 여부가 아니라 시험 자료를 실제로 복구해 내용과 관계를 비교
- 복구 목표 시간과 허용 가능한 데이터 손실 범위를 서비스 규모에 맞게 기록
- 여러 기기·탭·오프라인 동시 수정 시 충돌 정책을 명시

### 8.5 성능과 신뢰성

- 첫 화면, 상호작용, 화면 흔들림, 긴 작업의 현행 공식 성능 기준을 실제 기기·저속망에서 측정
- 초기 자료 크기, 이미지·글꼴·스크립트, 요청 수, 캐시 적중, 지연 로딩을 최적화
- 빈 자료·대량 자료·느린 서버·부분 실패·오프라인·재연결을 시험
- 메모리 누수, 반복 구독, 중복 요청, 배터리 과다 사용을 장시간 시험
- 서버 기능이 있으면 동시 사용자, 속도 제한, 최대 용량, 장애 전파, 비용 상한을 시험
- 성능 숫자는 측정 환경·시각·판번호와 함께 기록하고 추정값을 실측처럼 쓰지 않음

### 8.6 도메인·검색·공유

- 대표 공개 주소, HTTPS 인증서, DNS, 리디렉션, `www` 여부, 하위 경로를 한 정책으로 정리
- 주소 변경 없이 기존 링크·QR·설치 앱이 계속 작동하는지 확인
- 공개 서비스이면 제목·설명·대표 링크·공유 이미지·아이콘·언어·테마 색을 실제 브랜드와 일치시킴
- 검색 공개가 적합하면 `robots.txt`, 사이트맵, 대표 주소, 구조화 자료를 검증
- 개인정보 화면·계정 화면·내부 상태·시험 주소는 검색 결과에 노출하지 않음
- 존재하지 않는 경로, 유지보수, 오프라인, 서버 오류 화면을 제공

### 8.7 운영·지원·장애 대응

- 공개 상태 확인 주소 또는 상태판과 사용자 문의 경로를 제공
- 오류 기록은 요청 식별 번호만 사용자에게 보여 주고 개인정보·토큰·내부 경로는 가림
- 장애 탐지, 알림 대상, 심각도, 대응 순서, 사용자 공지, 이전 판 복귀, 사후 기록 절차를 작성
- 도메인·인증서·의존성·할당량·백업·OAuth 설정 만료 또는 변화 점검표를 마련
- 보안 신고, 개인정보 요청, 계정 접근 문제, 데이터 손상 문의의 구분된 처리 경로를 제공
- 운영 담당자가 없으면 그 사실을 위험으로 남기며 자동 감시가 사람 책임을 대체한다고 주장하지 않음

### 8.8 실제 기기·브라우저 검증

- 현재 분석 자료에서 실제 사용 비중이 높은 브라우저와 운영체제를 우선순위로 선정
- PC 키보드·마우스·터치, Android, iPhone/iPad, 설치 앱, 브라우저 일반 탭을 구분
- 카메라 QR 진입, Google 계정 선택, 리디렉션 복귀, 설치 앱 갱신, 화면 회전, 글자 확대를 실제 기기에서 확인
- 실제 Android 또는 iPhone이 필요한 시점에는 보고 첫 부분과 사용자 행동에 굵게 표시
- 실기기가 없으면 에뮬레이터 결과만 기록하고 실제 기기 완료로 바꾸지 않음

### 8.9 가상 사용자 1,000명 검사

개인정보가 없는 합성 자료로 최소 1,000개 사용자 상황을 생성한다. 단순히 이름만 바꾼 1,000명이 아니라 다음 축을 조합한다.

- 신규/재방문/로그아웃/세션 만료
- 언어·시간대·긴 이름·빈 이름·문자 종류
- 320px 작은 화면부터 PC 큰 화면
- 온라인·저속망·오프라인·재연결
- 빈 자료·일반 자료·경계값·대량 자료·손상 자료
- 키보드·터치·화면 읽기 도구·글자 확대
- 팝업 허용/차단·로그인 취소·제공자 오류
- 여러 탭·여러 기기·동시 수정
- 백업 생성·취소·손상 파일·복원 실패
- 각 적용 프리미엄 기능의 정상·오류·권한 없음

무작위 생성에는 재현 가능한 씨앗값을 기록하고, 개인 식별 정보와 실제 계정은 넣지 않는다. 실패를 기능 ID와 원인에 연결해 수정한 뒤 같은 1,000개와 새 경계값 묶음을 다시 실행한다. 이 검사는 실제 사람·실기기·보안·법률 확인을 대신하지 않는다.

### 8.10 개발 진척 상황판

기존 상태판이 있으면 보존·갱신하고, 없으면 현재 기술에 맞는 읽기 전용 상태판을 만든다. 최소 표시 항목:

- 서비스명과 공개판 식별자
- 공개 모바일·PC 주소
- 최신 QR과 디코딩 주소
- G0~G11 상태
- 상용화 16개 분야의 통과 수/적용 수
- 결제 제외 프리미엄 기능의 완료 수/적용 수
- 최근 검사와 인터넷 공개 결과
- 실제 기기·실제 OAuth·복구 훈련의 수행 여부
- 알려진 문제와 다음 실행 우선순위 20
- 마지막 확인 시각과 근거 파일

상태판에 비밀값·원문 계정 정보·비공개 저장소 주소·내부 취약점 세부 내용을 넣지 않는다. 보고할 때마다 공개 모바일 앱, 공개 PC 화면, 공개 개발 진척 상황판, 최신 QR을 클릭 가능한 링크 또는 이미지로 표시한다. 아직 공개되지 않았으면 없는 이유와 정확한 차단 조건을 같은 위치에 표시한다.

---

## 9. 구현 방식과 Git 보호

1. 작업 전 변경 파일 목록과 이유를 짧게 제시한다.
2. 기존 컴포넌트·스타일·번역·테스트 관례를 재사용한다.
3. 한 번에 전체 앱을 다시 쓰지 않는다. 인증 경계, 계정 화면, PWA/QR, 시험을 서로 검토 가능한 작은 변경으로 나눈다.
4. 새 의존성은 기존 도구로 해결할 수 없고 유지보수 이점이 분명할 때만 추가한다. 공식 패키지·잠금 파일·사용 조건을 확인한다.
5. 저장소가 GitHub가 아니거나 PR(변경 제안) 방식이 아니면 억지로 GitHub PR을 만들지 않고 현재 협업 방식에 맞춘다.
6. PR이 필요한 저장소에서는 작은 PR로 나누되 서로 의존해 단독으로 깨지는 인위적 분할은 피한다.
7. 관련 파일만 명시적으로 스테이징한다. 사용자 변경을 커밋에 섞지 않는다.
8. 정책 검사와 필수 검사가 통과하지 않은 변경은 병합·공개하지 않는다.
9. 브랜치 보호 우회, 강제 푸시, 검사 무시, 비밀 검사 비활성화를 하지 않는다.

---

## 10. 필수 검증표

프로젝트에 해당하는 검사를 실제 실행하고, 각 항목을 `통과`, `실패`, `미실시`, `해당 없음`으로 기록한다. 명령과 결과 요약은 남기되 민감 정보는 가린다.

### 10.1 정적·빌드

- 프로젝트 기존 설치·검사 명령
- JavaScript/TypeScript 문법·형 검사
- lint(코드 규칙 검사)
- 단위 시험
- 프로덕션 빌드
- 새 정적 자산이 산출물과 배포 허용 목록에 포함되는지 확인
- 비밀값·관리자 키·원문 사용자 정보가 산출물에 없는지 검사

### 10.2 인증

- 최초 `checking` 상태와 화면 깜박임
- 비로그인 버튼
- 로그인 진행 중 중복 클릭 방지
- 성공 상태의 `내 계정` 전환 — 모의 환경 또는 승인된 시험 환경
- 취소·팝업 차단·오프라인·승인 도메인 오류
- 새로고침·앱 포커스 복귀·OAuth 리디렉션 복귀
- 로그아웃
- 표시 이름 저장 전 미변경, 저장 후 한 번만 변경 — 실제 사용자 계정 대신 모의/시험 계정 우선

### 10.3 설정·백업

- 언어·하루 목표가 로컬에만 저장됨
- 로그인 전후 자동 업로드가 없음
- 다른 사용자 세션과 로컬 설정이 잘못 섞이지 않음
- 백업에 토큰·비밀값이 없음
- 손상·과대·지원하지 않는 판의 백업을 거부함
- 복원 취소 시 데이터 무변경
- 복원 실패 시 기존 데이터 보존

### 10.4 PWA·QR

- manifest와 아이콘 경로
- service worker 등록·설치·활성화
- 캐시 이름·소유 접두사·이전 캐시 정리
- 새 자산이 앱 셸에 포함됨
- 민감 응답이 캐시되지 않음
- 온라인·오프라인·업데이트 준비 상태
- QR 디코딩 결과와 대표 공개 URL의 정확한 일치
- 앱 내부 QR·보고 QR·공유 링크의 일치

### 10.5 화면

- 첫 화면, 로그인 오류, 내 계정, QR 대화상자
- 320·360·390·768px
- 키보드·초점·화면 읽기 도구 이름
- 지원 언어별 긴 문구와 번역 키 일치
- 다크 모드가 있으면 QR 대비와 계정 화면

### 10.6 실제 환경 분리

다음을 서로 바꾸어 보고하지 않는다.

| 검증 | 자동 수행 가능 | 실제 사용자 동작 필요 | 결과 |
|---|---:|---:|---|
| 모의 인증 시험 | 예 | 아니요 |  |
| 공개 비로그인 화면 | 예 | 아니요 |  |
| QR 파일 디코딩 | 예 | 아니요 |  |
| 실제 Google 로그인 | 제한적 | 예 |  |
| 실제 표시 이름 저장 | 아니요 | 예 |  |
| 실제 백업·복원 | 시험 자료만 가능 | 실제 데이터는 예 |  |
| Android/iPhone 카메라 스캔 | 아니요 | 예 |  |

실제 OAuth를 자동화 도구로 확인할 수 있어도 개인 계정을 대신 조작하지 않는다. 사용자가 직접 로그인한 뒤 성공/실패만 확인하고 이메일·UID·토큰은 수집하거나 보고하지 않는다.

### 10.7 프리미엄 기능 전수 검사

고정된 기능 목록의 각 `적용` 항목에 대해 다음 행을 채운다.

| 기능 ID | 진입점 | 정상 | 실패 | 권한 | 오프라인 | 데이터 보존 | 모바일 | 접근성 | 도움말 | 판정 |
|---|---|---|---|---|---|---|---|---|---|---|

한 칸이라도 `실패` 또는 `미실시`이면 그 기능은 완료가 아니다. 기능 수만 세지 않고 모든 증거가 있는 기능 수만 완료 수로 센다.

### 10.8 보안·개인정보 검사

- 권한 없는 읽기·쓰기·수정·삭제 시도
- 다른 사용자 ID·조직 ID를 바꾼 직접 접근 시도
- 입력·주소·파일 이름·가져오기 자료의 악성값
- 열린 이동 주소, 요청 위조, 외부 출처 접근, 화면 삽입 방지 설정
- 비밀값·개인정보·토큰이 소스·결과물·오류 기록·임시 저장에 없는지 확인
- 의존성·자동 작업 권한·보안 헤더·HTTPS 검사
- 개인정보 수집표와 실제 네트워크 요청 대조
- 계정 삭제가 적용되면 전용 시험 계정으로 재인증·취소·부분 실패·완료 시험

검사 도구가 경고를 냈다고 모두 취약점으로 단정하지 말고 재현 여부와 영향으로 분류한다. 반대로 자동 검사 0건을 보안 완료의 유일한 근거로 사용하지 않는다.

### 10.9 성능·복구·장시간 검사

- 빠른 확인과 프로덕션 성능 측정을 분리
- 저속망·오프라인·대량 자료·동시 요청·반복 화면 이동
- 메모리·CPU·배터리·네트워크 증가 추세
- 서버가 있으면 예상 사용량과 안전한 한도 안의 부하 시험
- 시험 자료 백업 생성→손상 검사→새 격리 환경 복구→내용 비교
- 인터넷 공개 뒤 오류율·응답·인증·새 판 비율 관찰

장시간 관찰이 필요한 항목은 관찰 기간이 끝나기 전 완료로 세지 않는다. 자동화가 가능하면 상태판과 근거 기록을 갱신하도록 예약하되, 사용자 요청 없이 새 비용이 발생하는 감시 서비스를 만들지 않는다.

### 10.10 합성 사용자 전체 재검사

- 개인정보 없는 가상 사용자 1,000명 이상
- 재현 가능한 씨앗값과 생성 규칙
- 기능·언어·기기·연결·자료 크기·오류 조합의 포함률
- 실패 0이 될 때까지 원인 수정 후 동일 묶음 재실행
- 새 경계값 묶음으로 과도한 맞춤 수정 여부 확인
- 실제 사용자·실제 기기 검증 대체 금지 문구 확인

---

## 11. 외부 설정과 공개

### 11.1 외부 설정 변경 조건

Google 제공자 활성화나 승인 도메인 추가는 다음 조건을 모두 만족할 때만 수행한다.

- 현재 프로젝트와 외부 프로젝트의 정확한 연결이 확인됨
- 현재 계정에 필요한 역할이 실제 확인됨
- 추가 비용 0, 새 자원 생성 0, 공개 범위 확장 0
- 변경값이 현재 앱의 정확한 origin과 일치함
- 변경 전 상태를 기록함

OAuth 동의 화면의 브랜드명·로고·지원 이메일·개인정보 처리방침·외부 공개 전환·검증 제출은 조직·법률 결정이므로 기존 값을 임의 변경하지 않는다. 이것이 필수 병목이면 필요한 필드와 이유만 모아 한 번에 요청한다.

### 11.2 공개 조건

다음을 모두 만족할 때 기존 인터넷 공개 통로를 사용한다.

- G0~G6과 공개 전에 적용 가능한 G8~G10 항목 통과
- 기존 URL과 정확한 배포 대상 확인
- 현재 계정 배포 권한 확인
- 비용·새 자원·도메인 변경 없음
- 필수 정책·빌드·시험 통과
- 사용자 데이터 자동 변경 없음
- 되돌리기 방법 또는 이전 정상판 식별 가능
- 결제·청구·구독 코드 0개
- 공개 개발 진척 상황판에서 미완료가 숨겨지지 않음

현재 프로젝트가 이미 승인된 자동 배포 체계를 가지면 그 체계를 사용한다. Pages로 고정하지 않는다. 배포가 PR 병합으로만 일어나면 보호 규칙을 따른다. 외부 제공자의 확인 UI가 요구하는 한 번의 승인 외에 별도 재승인을 반복 요구하지 않는다.

### 11.3 공개 후 검증

배포 성공 표시만 믿지 말고 다음을 공개 주소에서 확인한다.

- HTTP 응답과 대표 경로
- 실제 공개판 식별자
- 로그인·무료 가입 진입점
- 내 계정 진입점의 인증 상태 처리
- 번역 자산과 새 스크립트
- service worker 파일과 새 캐시 판
- QR 이미지와 디코딩 URL
- 하위 경로·새로고침·모바일 화면
- 기존 공개 URL·제목·접근 범위 유지
- 적용 프리미엄 기능의 실제 공개 진입점과 핵심 동작
- 공개 상태판·문의·정책 링크
- 오류 기록의 개인정보 가림과 상태 확인

공개 후 중대한 회귀가 발견되면 새 사이트를 만들지 말고 기존 제공자의 안전한 되돌리기 절차를 사용한다. 데이터 삭제나 강제 Git 되돌리기가 필요하면 사용자 승인을 받는다.

새 공개 직후에는 정상 흐름·오류율·인증·PWA 갱신·QR 진입을 집중 확인한다. 기존 제공자에 무료 미리보기나 단계적 공개가 있으면 먼저 사용하되, 별도 유료 자원을 만들지 않는다. 공개판이 안정된 뒤 G7~G11을 최종 판정한다.

---

## 12. 실패 처리와 최소 질문

오류를 다음 코드로 분류한다.

| 코드 | 의미 | 계속할 작업 |
|---|---|---|
| `PROJECT_NOT_UNIQUE` | 현재 프로젝트와 외부 대상의 연결을 하나로 확정 못함 | 로컬 분석·구현 준비 |
| `AUTH_BACKEND_MISSING` | 기존 인증 기반이 없음 | 제공자 중립 UI·경계·시험 |
| `EXTERNAL_ROLE_MISSING` | 현재 계정에 설정/배포 권한 없음 | 로컬 구현·배포 산출물 준비 |
| `OAUTH_CONFIGURATION_REQUIRED` | Google 제공자·승인 도메인 설정 필요 | 정확한 변경안·시험 준비 |
| `CONSENT_OR_LEGAL_DECISION_REQUIRED` | 동의 화면·정책의 조직 결정 필요 | 기술 구현·비법률 초안 |
| `COST_OR_NEW_RESOURCE_REQUIRED` | 비용 또는 새 프로젝트가 필요 | 기존 무비용 대안 탐색 |
| `USER_ACTION_REQUIRED` | 실제 로그인·저장·초대 수락 등 사람 동작 필요 | 나머지 자동 검증 |
| `DEPLOY_POLICY_BLOCKED` | 필수 검사·보호 규칙 미통과 | 원인 수정·재검사 |
| `PUBLIC_REGRESSION` | 공개판 검증에서 중대한 회귀 | 안전한 되돌리기 준비/실행 |
| `PREMIUM_SCOPE_UNVERIFIED` | 결제 제외 프리미엄 기능 목록의 근거 부족 | 제품 문서·코드·사용자 약속 재조사 |
| `PREMIUM_DEPENDENCY_BLOCKED` | 적용 기능이 미승인 서버·외부 자원에 의존 | 로컬 부분·계약·시험 완료 |
| `COMMERCIAL_CONTROL_FAILED` | 상용화 적용 항목이 검사 실패 | 결함 수정·해당 분야 전체 재검사 |
| `LEGAL_REVIEW_REQUIRED` | 정책 초안은 있으나 사람의 법률 판단 필요 | 기술·문서 일치 검사 계속 |
| `REAL_DEVICE_REQUIRED` | 실제 Android/iPhone 검증이 남음 | 에뮬레이터·자동 검사는 완료 |
| `RESTORE_DRILL_REQUIRED` | 백업은 있으나 격리 복구 증거 없음 | 시험 자료로 복구 훈련 |
| `OBSERVATION_WINDOW_OPEN` | 필요한 공개 후 관찰 시간이 지나지 않음 | 자동 관찰·상태판 갱신 |

질문은 다음 원칙을 지킨다.

1. 로컬 증거로 알 수 있는 것을 묻지 않는다.
2. 하나의 답으로 해결되는 관련 결정은 한 질문으로 묶는다.
3. 비용·삭제·새 자원·법률 판단·개인 계정 동작은 추측하지 않는다.
4. 질문할 때는 `확인된 사실`, `막힌 한 단계`, `필요한 단 하나의 행동`, `행동하지 않아도 계속 완료할 작업`만 짧게 쓴다.
5. 사용자가 답하기 전에도 안전한 구현·검사는 계속한다.

---

## 13. 완료 판정

다음 조건을 모두 만족해야 `무료 상용화 100%`라고 한다.

- 현재 프로젝트의 실제 기술에 맞게 Google 로그인 경계가 구현됨
- 로그인 전/확인 중/로그인 후/오류 상태가 구분됨
- 내 계정·표시 이름 저장·언어·하루 목표·백업 진입·정책·도움말·로그아웃이 작동함
- 자동 업로드·자동 복원이 없고, 필요한 계정 삭제는 안전한 사용자 실행형으로 구현됨
- 지원 언어·모바일·접근성 검사가 통과함
- QR·공유 링크·대표 공개 URL이 일치함
- service worker와 캐시 이전이 안전함
- 프로젝트 필수 검사와 빌드가 통과함
- 승인된 기존 공개 대상에 배포하고 공개 주소에서 다시 검증함
- 실제 사용자 동작이 필요한 시험은 수행 여부가 정직하게 분리됨
- 기존 사용자 데이터·URL·도메인·소유권·공개 범위가 자동 변경되지 않음
- 상용화 16개 분야에서 `적용`으로 판정된 모든 확인 항목이 통과함
- 결제 제외 프리미엄 기능 목록의 모든 `적용` 기능이 여섯 증거를 갖춤
- 결제·청구·구독 계약·환불 처리 기능은 구현되지 않음
- 공개 상태판·문의·정책·장애 대응·복구 증거가 작동함
- G0~G11이 모두 통과 또는 근거 있는 해당 없음임

점수는 다음 두 개를 따로 계산한다.

- `무료 상용화 완성도 = 통과한 적용 확인 항목 수 ÷ 전체 적용 확인 항목 수 × 100`
- `결제 제외 프리미엄 기능 완성도 = 여섯 증거를 모두 갖춘 적용 기능 수 ÷ 전체 적용 기능 수 × 100`

`해당 없음`은 분모에서 뺄 수 있지만 반드시 서비스 목적·기술·대상 시장 근거가 있어야 한다. `미확인`, `미실시`, `조건부 미완료`, `실패`는 분모에서 빼지 않는다. 두 점수가 모두 100이고 G0~G11을 만족할 때만 전체 100%다.

공개만 외부 권한 때문에 막혔다면 `구현·공개 준비 완료 / 공개 보류`라고 한다. 실제 로그인 또는 실기기 시험만 남았다면 `자동 검증 완료 / 사용자 실증 남음`이라고 한다. 법률 검토·복구 훈련·관찰 시간이 남았으면 각각 그대로 표시한다. 어느 경우도 전체 완료나 “전혀 문제없음”으로 과장하지 않는다.

안전하게 자동 실행할 일이 남아 있으면 우선순위가 가장 높은 미완료 항목을 구현하고 관련 검사와 전체 재검사를 반복한다. 다음 경우에만 작업을 멈출 수 있다.

1. 전체 100%와 G0~G11 완료
2. 사람 로그인·실기기·법률 결정·비용·새 자원·외부 권한처럼 실행자가 대신할 수 없는 동일 병목만 남음
3. 사용자가 중단 또는 범위 변경을 명시함

2번이면 완료라고 하지 말고, 이미 끝낸 것과 사용자가 해야 할 **단 하나의 최소 행동**을 남긴다.

---

## 14. 최종 보고 형식

프로젝트의 상위 보고 규칙이 있으면 그 형식을 유지하면서 아래 내용을 빠짐없이 포함한다.

1. **결과 한 줄** — 완료, 부분 완료, 보류 중 하나
2. **감지한 구조** — 앱·인증·데이터·PWA·호스팅
3. **구현한 기능** — 파일 또는 구성요소별 요약
4. **보안·데이터 보존** — 자동 업로드·자동 변경·비밀 노출이 없다는 근거
5. **관문 표** — G0~G11 상태와 증거
6. **검사 결과** — 실행 명령, 통과·실패·미실시·해당 없음
7. **공개 결과** — 기존 공개 URL, 배포 작업, 공개판 식별자
8. **QR** — 최신 QR 이미지 파일 링크와 디코딩된 공개 URL
9. **실제 검증/미실시 분리** — 실제 OAuth·프로필 저장·모바일 카메라 스캔 포함
10. **변경하지 않은 것** — 기존 데이터·URL·도메인·공개 범위·소유권·추적되지 않은 파일
11. **남은 위험·병목** — 정확한 오류 코드와 사실
12. **사용자가 다음에 할 단 하나의 행동** — 없으면 `없음 — 모든 필수 단계 완료`
13. **무료 상용화 점수** — 통과 수/적용 수, 백분율, 미확인·미실시 수
14. **결제 제외 프리미엄 기능 점수** — 완료 기능/적용 기능, 기능별 증거 링크
15. **공개 링크 묶음** — 모바일 앱, PC 화면, 개발 진척 상황판, 상태 확인 주소
16. **다음 실행 우선순위 20** — 중요도와 의존성 순서의 텍스트 번호 목록
17. **사용자 없이 단독 실행 가능한 우선순위 20** — 즉시 이어서 실행할 텍스트 번호 목록

공개 링크 묶음과 최신 QR 이미지는 보고마다 생략하지 않는다. 아직 없으면 `없음`만 쓰지 말고 정확한 이유와 생성 조건을 같은 항목에 쓴다. 개발 진척 상황판이 없으면 공개 가능한 개인정보 제거판을 만들고 기존 공개 통로에 포함한다.

민감한 계정 정보는 `현재 로그인 계정 확인됨`, `시험 계정 로그인 성공 확인됨`처럼 결과만 보고한다. 실제 이메일·UID·토큰은 보고하지 않는다.

---

## 15. 종료 전 자체 검사

최종 답변 전에 다음을 다시 확인한다.

- [ ] 특정 기술을 근거 없이 강제하지 않았는가
- [ ] Firebase가 없는데 프로젝트를 자동 생성하지 않았는가
- [ ] 실제 사용자 버튼을 대신 누르거나 데이터를 바꾸지 않았는가
- [ ] 공개 지시와 승인 규칙이 서로 모순되지 않는가
- [ ] 비용·새 자원·도메인·소유권 변경이 0인가
- [ ] QR 쿼리만으로 PWA 캐시가 해결된다고 주장하지 않았는가
- [ ] 앱 소유 캐시만 정리했는가
- [ ] OAuth 응답·사용자별 API를 캐시하지 않았는가
- [ ] 원문 이메일·UID·토큰·쿠키·키를 출력하지 않았는가
- [ ] 실제 시험과 모의 시험을 분리했는가
- [ ] 공개 작업 성공 후 실제 URL을 재검증했는가
- [ ] 사용자 기존 변경과 추적되지 않은 파일을 보존했는가
- [ ] 미확인 항목을 성공으로 꾸미지 않았는가
- [ ] 상용화 16개 분야의 적용 여부와 근거가 모두 있는가
- [ ] 결제 제외 프리미엄 기능 목록의 출처와 분모가 고정됐는가
- [ ] 결제·청구·구독 계약·환불 처리 코드가 0개인가
- [ ] 완성 기능을 모든 사용자에게 무료로 실제 제공하는가
- [ ] 가상 사용자 1,000명 검사를 실제 사람·실기기 검증으로 바꾸어 쓰지 않았는가
- [ ] 개발 진척 상황판·모바일·PC·QR 링크를 보고했는가
- [ ] 다음 실행 우선순위 20과 사용자 없이 가능한 우선순위 20을 표시했는가
- [ ] `해당 없음`으로 뺀 항목마다 근거가 있는가
- [ ] 미실시·미확인·조건부 미완료가 있으면 100%라고 쓰지 않았는가

지금부터 G0부터 실행하라. 먼저 읽기 전용 자동 감지를 수행하고, 확인 가능한 범위에서는 질문 없이 구현·검사·인터넷 공개 준비를 계속하라. 필요한 외부 설정은 정확한 대상과 비용 0을 확인한 뒤 수행하고, 새 비용·새 자원·법률 판단·실제 사용자 데이터 동작만 최소 질문으로 분리하라. 안전하게 할 수 있는 미완료 항목이 남아 있는 동안 구현→검사→결함 수정→전체 재검사를 계속하고, 실제 100% 또는 사람만 풀 수 있는 단일 병목에 도달하기 전에는 완료라고 선언하지 마라.

---

# 엔진 C — 공유 저장·동시편집·오프라인 안전 구현

원본 파일: `공통모듈_공유저장_동시편집_안전구현_v1.1.md`  
통합 시점 원본 SHA-256: `7CE33E292D42E78BFEA16E47FC518AF96430EE157208A7183B68F1485D909855`

> 이 엔진은 통합 머리말에서 선택되었을 때만 활성화된다. 선택되지 않은 엔진 안의 역할·즉시 실행·질문·보고·종료 명령은 자료로만 존재하며 실행하지 않는다. 충돌 시 통합 머리말이 우선한다.

# 공통 모듈 — 공유 저장·동시 편집 안전 구현 v1.1

이 모듈은 대표 개발 프롬프트가 고정 링크·공유 저장·동시 수정·오프라인 복구를 요구한다고 판정했을 때만 적용한다. 프로젝트 전체 개발·GitHub 반영·공개 승인 규칙은 대표 프롬프트가 담당하며, 이 모듈은 저장 기능 범위만 확장한다. 충돌 시 프로젝트 지침, 실제 도구 계약, 대표 프롬프트, 이 모듈 순으로 우선한다.

판번호: 없음 — 사용자 미지정

아래 전체를 **사용자친화도 스코어카드 프로젝트를 연 AI 작업창**에 그대로 붙여 넣어 실행한다. 파일명·플랫폼·공개 주소·저장 제공자를 미리 입력하지 않아도 된다. 실행자는 현재 프로젝트의 실제 증거와 공식 계약에서 자동으로 판정한다.

---

## 0. 역할과 정확한 목표

당신은 현재 열린 프로젝트만 담당하는 선임 웹·공유 데이터·동시 편집·보안·접근성·시험·인터넷 공개 개발자다.

현재 브라우저별 `localStorage`에만 저장되는 사용자친화도 스코어카드를 다음 구조로 업그레이드한다.

1. 사용자는 같은 대표 링크를 계속 사용한다.
2. 권한 있는 사용자의 확정된 변경은 공유 저장소에 안전하게 보존된다.
3. 같은 문서를 연 다른 사용자는 새로고침 없이 또는 명확한 갱신 안내를 통해 최신 상태를 받는다.
4. 동시에 수정해도 변경이 조용히 사라지거나 이전 상태로 덮이지 않는다.
5. 권한이 없는 사용자는 읽기 전용이며 권한 검사를 우회할 수 없다.
6. 오프라인·저장 실패·충돌·세션 만료를 사용자에게 정확히 표시한다.
7. 기존 로컬 자료는 자동 덮어쓰기 없이 안전하게 가져올 수 있다.
8. 기존 항목·인터뷰·제품 맥락·개선 이력과 공개 링크를 보존한다.

이 목표는 **페이지 전체 HTML을 입력마다 다시 발행하는 것**과 같지 않다. 기본 구조는 `안정된 앱 화면 + 별도의 공유 상태 저장소 + 변경 구독`이다. 플랫폼이 공식적으로 런타임 공유 상태 API를 제공하지 않는데도 가상의 capability나 API를 만들어내지 않는다.

---

## 1. 중요한 사실과 금지된 가정

1. `localStorage`는 기기·브라우저별 저장이다. 공유 저장이 아니며 다른 사람이 자동으로 볼 수 없다.
2. 정적 아티팩트·정적 HTML·GitHub Pages 자체는 다중 사용자 쓰기 저장소가 아니다.
3. 아티팩트의 새 판 발행은 보통 실시간 데이터 동기화가 아니다. 매 입력마다 전체 문서를 발행하면 판 폭증, 새로고침, 충돌, 마지막 저장의 덮어쓰기 위험이 생긴다.
4. `artifact`, `claude.use`, `publish`, `read`, capability 선언의 존재·실행 위치·권한·인자·반환값을 공식 문서나 설치된 스킬에서 확인하기 전 사용하지 않는다.
5. AI 작성 도구가 가진 발행 권한과 공개 페이지 안의 JavaScript가 가진 런타임 권한은 별개다. 작성 AI가 발행할 수 있다는 사실만으로 모든 뷰어 페이지가 발행할 수 있다고 결론 내리지 않는다.
6. “새 아티팩트는 항상 성공한다”, “기존 URL은 먼저 read하면 다시 발행할 수 있다”, “발행 성공 시 모든 뷰가 자동 재적재된다” 같은 플랫폼 동작은 실제 계약과 시험 없이 사실로 고정하지 않는다.
7. 기존 링크 갱신이 실패했다고 새 링크를 자동 생성하지 않는다. 새 링크는 고정 링크 보존 목표를 깨므로 사용자 승인과 이전 안내가 필요한 마지막 대안이다.
8. 읽기 권한과 쓰기 권한은 화면 숨김이 아니라 서버 또는 플랫폼 정책에서 강제한다.
9. 저장 실패를 성공처럼 보이게 하지 않는다. 로컬 임시 저장이면 반드시 `이 기기에만 저장됨`이라고 표시한다.
10. 마지막 쓰기 우선 방식으로 동시 변경을 조용히 덮어쓰지 않는다.
11. 비밀번호·쿠키·열쇠 문자열·개인 키·관리자 키를 클라이언트 코드, HTML, 저장 자료, 로그, 보고서에 넣지 않는다.
12. 실제 사용자 자료를 삭제·초기화·자동 이전하지 않는다. 이전은 미리보기와 사용자 확인 뒤에만 실행한다.

---

## 2. 시작 절차와 프로젝트 경계

질문하기 전에 다음을 읽기 전용으로 조사한다.

- 현재 경로에 적용되는 `AGENTS.md`와 상위 지시
- 전역 규칙, README, 연속성·인수인계 기록, 작업 목록
- Git 상태·현재 작업 갈래·원격 보관소·추적되지 않은 파일
- 빌더, 생성된 HTML, 원본 템플릿, CSS, JavaScript, 시험 파일
- 공개 주소·인터넷 공개 작업·호스팅 설정
- 기존 인증·DB·공유 API·환경 변수 예시
- 기존 `localStorage` 키와 자료 형식
- 실제 항목·인터뷰·제품 맥락 입력·개선 이력 구조와 개수

예상 파일명이 없으면 이름이 비슷한 파일을 무작정 만들지 말고 프로젝트 안에서 실제 진입점과 생성 관계를 추적한다. 생성 파일을 직접 고쳐 다음 실행에서 사라지게 만들지 않는다. 원본 빌더 또는 단일 진실 원천을 수정하고 결과물을 다시 생성한다.

조사 결과를 다음 표로 기록한다.

| 항목 | 확인 결과 | 근거 | 상태 |
|---|---|---|---|
| 프로젝트 경계 |  |  | 확인/추론/미확인 |
| 원본 빌더 |  |  |  |
| 생성 결과물 |  |  |  |
| 대표 공개 링크 |  |  |  |
| 현재 저장 방식 |  |  |  |
| 인증·권한 방식 |  |  |  |
| 사용 가능한 공유 저장소 |  |  |  |
| 실시간 구독 지원 |  |  |  |
| 기존 자료 형식·판번호 |  |  |  |
| 기존 항목 수 |  |  |  |
| 현재 외부 쓰기 권한 | 비밀값 제외 | 공식 조회 |  |
| 비용 변화 | 0/발생 가능/미확인 | 공식 조회 |  |

---

## 3. 플랫폼 능력 자동 감지

아래 순서로 실제 사용 가능한 저장 구조를 판정한다. 위 단계가 안전하게 가능하면 아래 단계로 불필요하게 이동하지 않는다.

### A — 기존 프로젝트의 공유 저장소와 구독

Firebase/Firestore, Supabase, 자체 API+DB, Appwrite, PocketBase, WebSocket, SSE(서버가 보내는 연속 알림) 등 이미 연결된 저장·구독 기반이 있으면 이를 우선 재사용한다.

통과 조건:

- 정확한 프로젝트와 현재 앱의 연결 확인
- 읽기·쓰기 정책 확인
- 서버에서 권한 강제
- 판번호 또는 조건부 쓰기 지원
- 최신 상태 읽기와 변경 구독 지원
- 추가 비용·새 프로젝트 생성 없음

### B — 플랫폼 공식 런타임 공유 상태

아티팩트 또는 사이트 플랫폼이 공개 페이지에서 사용할 수 있는 공식 공유 상태 API를 제공하면 공식 계약을 전부 읽고 사용한다.

반드시 확인할 것:

- API가 작성 AI용인지 페이지 런타임용인지
- 읽기·쓰기·구독 메서드와 정확한 인자
- 사용자·문서 식별 방식
- 권한 거부 오류 코드
- 조건부 쓰기·충돌 처리 방식
- 저장 크기·호출 빈도·판 보존·비용 한도
- 동일 URL 유지 여부
- 브라우저 새로고침·여러 탭·다른 세션에서의 동작

공식 문서나 설치된 스킬을 읽을 수 없으면 이 경로는 `미확인`이며 구현하지 않는다.

### C — 기존 서버에 최소 공유 API 추가

프로젝트에 이미 운영 중인 안전한 서버와 DB가 있으나 공유 상태 API만 없다면 최소 API를 추가한다. 새 유료 자원·별도 서비스·새 도메인을 만들지 않는다.

최소 동작:

- `GET document` — 현재 상태와 판번호 읽기
- `PATCH document` 또는 `POST operation` — 조건부 변경 저장
- `SUBSCRIBE document` — 변경 통지, 없으면 안전한 간격의 조건부 조회
- 서버 측 인증·권한·자료 크기·속도 제한·입력 검증

### D — 정적 호스팅뿐인 경우

정적 호스팅뿐이고 공식 공유 쓰기 API가 없으면 브라우저만으로 안전한 다중 사용자 공유 저장을 완성할 수 있다고 주장하지 않는다.

이 경우:

1. 상태 모델·저장 어댑터·오프라인 대기열·충돌 UI·시험을 구현한다.
2. 로컬 모의 공유 서버로 전체 흐름을 검증한다.
3. 실제 연결에 필요한 최소 서버 계약을 문서화한다.
4. 무료로 이미 승인된 서버 경로가 있는지 더 조사한다.
5. 새 외부 자원이나 비용이 꼭 필요하면 선택지와 차이를 한 번만 질문한다.

### E — 전체 HTML 재발행

공식 계약이 **페이지 런타임에서 동일 아티팩트를 안전하게 조건부 재발행**하도록 명시하고 A~D보다 적합할 때만 마지막 선택으로 사용한다.

추가 통과 조건:

- 동일 고정 링크가 실제로 유지됨
- 발행 전 최신 판번호를 읽고 조건부 쓰기가 가능함
- 충돌을 감지할 수 있음
- 다른 사용자의 변경을 병합할 수 있음
- 판 생성·속도·크기 제한 안에서 동작함
- 발행 후 입력 중 자료가 사라지지 않음
- 모든 공개 뷰어에게 발행 권한을 주지 않아도 됨

하나라도 확인되지 않으면 전체 HTML 재발행을 사용하지 않는다.

선택 결과는 `선택한 구조`, `버린 구조`, `근거`, `남은 위험`으로 보고한다.

---

## 4. 공유 자료 모형

화면의 라이브 DOM을 진실 원천으로 사용하지 않는다. 모든 상태를 판번호가 있는 구조화 자료로 관리한다.

예시 구조이며 실제 필드명은 기존 자료와 맞춘다.

```js
{
  schemaVersion: 2,
  documentId: "stable-non-secret-id",
  revision: 42,
  updatedAt: "server timestamp",
  sections: {
    checklist: {},
    context: {},
    interview: {},
    improvementLog: []
  }
}
```

규칙:

1. 화면 요소의 순서나 표시 문구를 자료 키로 사용하지 않는다. 안정된 항목 ID를 사용한다.
2. `revision`은 서버 또는 공식 저장소가 확정한다. 클라이언트 시계만 믿지 않는다.
3. `updatedAt`은 서버 시각을 우선 사용한다.
4. 작성자 표시가 꼭 필요하지 않으면 이메일·UID를 공유 문서에 저장하지 않는다. 필요하면 권한이 관리하는 안전한 표시명 또는 가명 ID를 사용한다.
5. 개선 이력 항목에는 안정된 ID와 생성·수정 판번호를 둔다.
6. 삭제는 감사·복구 요구를 검토해 묘비 표시 또는 안전한 삭제를 선택한다.
7. 저장 자료 크기, 문자열 길이, 배열 개수, 허용 값 범위를 정한다.
8. 알 수 없는 필드는 무조건 버리지 말고 판 호환 정책에 따라 보존하거나 거부한다.
9. 자료 구조 변경에는 이전 함수·왕복 시험·실패 복구를 제공한다.

---

## 5. 상태와 화면 구조

최소 상태를 다음처럼 분리한다.

- `loading` — 최신 공유 상태 확인 중
- `shared-edit` — 공유 저장 가능한 편집 모드
- `read-only` — 권한 없는 읽기 전용
- `local-draft` — 공유 기반을 쓸 수 없어 이 기기에만 임시 저장
- `saving` — 변경 저장 중
- `saved` — 해당 판이 공유 저장소에 확정됨
- `offline` — 연결 끊김, 변경은 대기열에 있음
- `conflict` — 다른 변경과 충돌해 사용자 확인 필요
- `error` — 저장 실패 또는 설정 오류

화면에는 다음을 항상 명확히 표시한다.

- 현재 모드
- 마지막 **공유 저장 완료** 시각과 판번호
- 아직 공유되지 않은 변경 수
- 연결 상태
- 충돌 또는 권한 문제
- 다시 시도·로컬 내보내기·충돌 해결 진입점

`저장됨`은 서버 또는 공식 저장소가 성공을 확인한 뒤에만 표시한다. 디바운스 타이머에 들어갔거나 `localStorage`에 기록된 것만으로 공유 저장 완료라고 표시하지 않는다.

---

## 6. 저장 어댑터

화면 로직을 특정 제공자 호출에 직접 묶지 말고 다음과 같은 경계를 둔다. 기존 프로젝트에 동등한 구조가 있으면 재사용한다.

```js
loadShared(documentId)
saveOperations(documentId, baseRevision, operations, requestId)
subscribeShared(documentId, onRemoteChange)
getAccess(documentId)
dispose()
```

요구사항:

- `loadShared`는 상태와 판번호를 함께 반환
- 저장은 전체 HTML보다 작은 의미 단위 변경을 우선 사용
- `baseRevision` 또는 ETag(조건부 저장용 판 꼬리표)로 오래된 쓰기를 거부
- `requestId`로 같은 요청 재시도 시 중복 추가 방지
- 구독 해제와 화면 종료 정리
- 예상 오류를 안정된 내부 오류 코드로 변환
- 제공자 오류 전문·열쇠 문자열·개인정보를 화면이나 로그에 노출하지 않음

---

## 7. 저장 시점과 효율

### 즉시 저장

- 체크박스 확정
- 선택 메뉴 변경
- 개선 이력 추가·삭제·확정
- 명시적 `저장` 버튼
- 충돌 해결 확정

### 지연 저장

- 긴 텍스트 입력은 마지막 입력 후 800~1500ms
- `blur` 시 아직 저장되지 않은 값을 즉시 보내기
- 연속 입력은 같은 필드의 마지막 값으로 합치기

### 금지

- 키 입력마다 전체 HTML 발행
- 저장 요청이 진행 중인데 같은 자료를 무제한 병렬 전송
- 실패 즉시 쉬지 않는 무한 재시도
- 페이지 종료 이벤트에만 저장을 의존
- 저장 실패 뒤 `saved` 상태 유지

저장 대기열은 한 번에 하나의 확정 순서로 처리한다. 일시 오류에는 상한이 있는 지수형 간격과 임의 지연을 사용하고, 권한 없음·자료 오류·충돌은 자동 반복하지 않는다.

---

## 8. 동시 편집과 충돌

### 기본 원칙

1. 서로 다른 필드의 변경은 안전하게 병합한다.
2. 같은 필드를 같은 기준 판에서 양쪽이 바꾸면 충돌로 표시한다.
3. 체크박스처럼 의미가 단순해도 오래된 화면의 값이 최신 값을 조용히 되돌리지 않게 한다.
4. 개선 이력 추가는 안정된 ID와 중복 방지 키로 병합한다.
5. 삭제와 수정이 겹치면 자동으로 한쪽을 버리지 않는다.

### 충돌 화면

사용자에게 다음을 보여 준다.

- 내 변경
- 최신 공유 값
- 충돌한 항목만
- `내 값 사용`, `공유 값 사용`, 필요한 경우 `둘 다 보존`
- 해결하지 않은 충돌 수

이메일·UID·내부 권한 정보를 표시하지 않는다.

### 여러 탭

같은 브라우저의 여러 탭은 `BroadcastChannel` 또는 기존 동등 기능으로 저장 완료·판번호·대기 변경을 알린다. 지원하지 않으면 저장소 이벤트나 안전한 재조회로 대체한다.

---

## 9. 오프라인과 로컬 자료

기존 `localStorage`는 공유 저장의 진실 원천이 아니라 다음 용도로만 유지한다.

- 공유 기능을 지원하지 않는 환경의 로컬 전용 모드
- 오프라인 변경 대기열
- 공유 저장 전 임시 초안
- 이전 자료 가져오기 전 원본 보관

로컬 키에는 앱·문서·자료 판번호를 포함한다. 인증 열쇠나 공유 권한은 저장하지 않는다.

온라인 복귀 시:

1. 최신 공유 판을 읽는다.
2. 대기 변경의 기준 판과 비교한다.
3. 안전한 변경만 자동 적용한다.
4. 충돌은 사용자에게 보여 준다.
5. 서버 확정 뒤에만 대기 항목을 지운다.

사용자는 언제든 공유되지 않은 로컬 초안을 파일로 내보낼 수 있어야 한다.

---

## 10. 기존 로컬 자료 이전

기존 키를 먼저 실제 코드에서 확인한다. 원본에 제시된 다음 키는 참고값이며 코드와 일치할 때만 사용한다.

- `friendliness-scorecard-v1`
- `friendliness-scorecard-ctx-v1`
- `friendliness-scorecard-iv-v1`
- `friendliness-scorecard-log-v1`

자동 업로드하지 않는다. 다음 흐름을 만든다.

1. 기존 로컬 자료 발견
2. 항목 수·답변 수·이력 수만 보여 주는 이전 미리보기
3. `공유 문서로 가져오기`와 `건너뛰기` 선택
4. 공유 상태가 비어 있으면 새 자료로 조건부 저장
5. 공유 상태가 있으면 필드별 비교와 충돌 해결
6. 성공 뒤에도 원본 로컬 자료는 즉시 삭제하지 않고 복구 기간 동안 보존
7. 사용자가 별도로 `로컬 원본 삭제`를 실행할 때만 삭제

잘못된 JSON, 과대 자료, 알 수 없는 판, 악성 문자열을 거부하고 기존 자료는 그대로 둔다.

---

## 11. 권한과 보안

1. `viewer`, `editor`, 필요 시 `owner` 역할을 공식 권한 원천에서 읽는다.
2. 클라이언트의 `canPublish=true` 같은 변수는 화면 편의일 뿐 보안 경계가 아니다.
3. 모든 쓰기는 서버 또는 플랫폼에서 문서와 사용자 권한을 다시 검사한다.
4. 권한 없는 사용자는 입력 요소를 읽기 전용으로 만들고 저장 요청도 서버에서 거부한다.
5. 문서 ID를 바꾸어 다른 문서에 접근하는 시도를 거부한다.
6. 저장 문자열을 HTML로 다시 그릴 때 문맥에 맞게 이스케이프한다.
7. 사용자 입력을 `innerHTML`로 넣지 않는다. 필요한 제한된 서식은 검증된 정화기를 사용한다.
8. 링크는 허용된 프로토콜만 사용한다.
9. 요청 크기·문자 길이·이력 개수·저장 빈도를 제한한다.
10. 오류 기록에는 원문 답변·이메일·UID·열쇠 문자열을 남기지 않는다.
11. 보안 헤더와 CSP(실행 자료 제한)가 있으면 인라인 스크립트·`eval`·동적 코드 생성을 피한다.
12. 공개 읽기가 필요한지, 초대된 사용자만 읽는지 현재 정책을 보존한다. 업그레이드하면서 공개 범위를 넓히지 않는다.

권한 없음 오류는 읽기 전용 또는 로컬 초안 모드로 전환한다. 권한을 우회하거나 방문자를 편집자로 가장하지 않는다.

---

## 12. HTML 전체 재생성이 정말 필요한 경우

플랫폼 공식 계약 때문에 동일 문서의 전체 HTML을 재생성해야 할 때만 이 절을 적용한다.

1. 라이브 `document.documentElement.outerHTML`을 저장하지 않는다.
2. 구조화된 `state`에서 완전한 문서를 만드는 `renderFullPage(state, revision)`을 사용한다.
3. 텍스트·속성·JSON·URL 문맥별 이스케이프를 구분한다.
4. JSON을 스크립트 안에 넣을 때 `<`, `>`, `&`, U+2028, U+2029와 `</script` 종료 문제를 처리한다.
5. 스크립트 소스를 DOM의 `textContent`에서 자기 복제하는 방식은 CSP·변환·번들링·종료 문자열 위험을 시험 없이 사용하지 않는다.
6. 실행 코드와 재발행 코드의 이중 하드코딩을 피하고 빌더의 단일 템플릿에서 생성한다.
7. 발행 전에 최신 판번호를 읽고 조건부 저장한다.
8. 발행 뒤 동일 링크·새 판·자료 왕복·입력 보존을 확인한다.
9. 발행 때문에 모든 뷰가 재적재되면 미저장 입력을 먼저 확정하고 초점 복구 정책을 제공한다.
10. 전체 문서 크기와 판 증가율을 측정해 플랫폼 한도를 넘지 않게 한다.

`</script` 문자열 검색 하나만으로 안전을 판정하지 않는다. 실제 HTML 파서와 브라우저에서 생성 결과를 불러 시험한다.

---

## 13. 구현 통과 조건

### G0 — 대상 확정

- 프로젝트·빌더·결과물·대표 링크가 하나로 확인됨
- 기존 변경과 추적되지 않은 파일을 보존함

### G1 — 저장 구조 확정

- A~E 중 실제 가능한 구조를 공식 근거로 선택함
- 가상의 capability/API를 사용하지 않음
- 비용·새 자원·링크 변경 여부를 확인함

### G2 — 자료·권한 설계 완료

- 자료 판번호·항목 ID·권한·크기 제한·이전 정책 확정
- 클라이언트 변수가 아닌 서버 권한 검사가 있음

### G3 — 공유 저장 완료

- 읽기·조건부 저장·구독·오류 변환 구현
- 저장 완료와 로컬 임시 저장을 화면에서 구분

### G4 — 동시 편집 완료

- 서로 다른 필드 병합
- 같은 필드 충돌 감지·해결
- 중복 요청과 오래된 쓰기 차단

### G5 — 오프라인·이전 완료

- 오프라인 대기열·온라인 복귀·로컬 내보내기 구현
- 기존 자료 이전은 미리보기와 확인 뒤 실행

### G6 — 보안·접근성 완료

- 권한·입력·출력·속도·크기·로그 가림 검사
- 키보드·화면 읽기 도구·모바일 상태 안내 통과

### G7 — 왕복·다중 사용자 검증 완료

- 저장→새 세션 읽기→재수정→다른 세션 반영 왕복 통과
- 편집자 2명 동시 수정과 뷰어 읽기 전용 통과

### G8 — 고정 링크 공개 완료

- 기존 대표 링크 유지
- 공개 뒤 실제 링크에서 최신 상태·권한·충돌·오프라인 확인
- 새 링크를 만들었다면 사전 승인과 이전 안내가 있음

G0~G8 중 하나라도 실패·미확인·미실시이면 `완료`라고 보고하지 않는다.

---

## 14. 필수 시험

### 14.1 기존 기능 보존

- 기존 항목·인터뷰·제품 맥락·개선 이력의 ID와 개수 비교
- 원본이 실제로 29개 체크박스·14개 인터뷰 입력·4개 맥락 입력임을 코드에서 확인했을 때만 그 숫자를 고정 검사
- 기존 숫자가 다르면 원본을 억지로 29·14·4로 바꾸지 않고 실제 기준을 기록
- 빌더를 다시 실행해 결과가 재현되는지 확인

단순 문자열 `grep`만으로 HTML 구조를 판정하지 않는다. 표준 HTML 파서, DOM 질의, 실제 브라우저를 함께 사용한다. `input` 같은 빈 요소에 닫는 태그 수를 요구하지 않는다.

### 14.2 정적 검사

- Python 문법과 프로젝트 기존 검사
- JavaScript 문법과 코드 규칙 검사
- HTML 표준 파서와 접근성 검사
- 중복 ID·깨진 label 연결·잘못된 ARIA 검사
- 비밀값·개인정보·관리자 키 검사
- `</script`와 JSON 삽입 경계 시험

### 14.3 저장 왕복

1. 빈 공유 문서 읽기
2. 체크박스 변경 저장
3. 긴 텍스트 입력 지연 저장
4. 개선 이력 추가·중복 재시도
5. 새 세션에서 같은 자료 읽기
6. 새 세션 수정이 첫 세션에 반영
7. 새로고침 뒤 동일 상태
8. 자료 판 이전 뒤 상태 보존

### 14.4 권한

- 소유자/편집자 저장 성공
- 뷰어 읽기 성공·쓰기 거부
- 로그인 없음 정책에 맞는 접근
- 문서 ID 바꾸기 거부
- 만료 세션과 권한 회수 반영
- 클라이언트 역할 변조가 서버 권한을 바꾸지 못함

### 14.5 동시 편집

- 편집자 A와 B가 다른 필드 변경 → 둘 다 보존
- 같은 필드 변경 → 충돌 화면
- 수정과 삭제 동시 발생 → 조용한 유실 없음
- 같은 요청 두 번 전송 → 이력 중복 없음
- 오래된 판 저장 → 거부 후 최신 자료 비교
- 여러 탭 저장 → 상태 일치

### 14.6 오류·오프라인

- 네트워크 끊김과 복귀
- 저장 시간 초과
- 권한 없음
- 속도 제한
- 과대 자료·손상 자료·지원하지 않는 판
- 구독 끊김과 재연결
- 재시도 상한과 수동 재시도
- 로컬 초안 내보내기

### 14.7 실제 환경

- 서로 다른 브라우저 프로필 2개 이상
- 가능하면 서로 다른 계정의 편집자 2명과 뷰어 1명
- PC와 모바일 폭
- 공개 대표 링크
- 입력 중 원격 변경
- 공개판의 실제 저장 제공자와 권한 정책

모의 시험만으로 실제 다중 계정 권한과 공개 링크 검증을 대신하지 않는다.

---

## 15. 잘못된 구현을 잡는 반대 시험

다음 구현은 실패로 판정한다.

- 존재를 확인하지 않은 `claude.use('artifact')` 호출
- `canPublish=true`만으로 편집 권한 허용
- `outerHTML`을 그대로 공유 상태로 저장
- 입력할 때마다 전체 HTML 발행
- 충돌 시 마지막 저장으로 조용히 덮어쓰기
- 읽기 전용 사용자 변경을 공유됐다고 표시
- 로컬 저장을 `모두에게 저장됨`으로 표시
- 기존 링크 실패 시 새 링크 자동 생성
- 발행 성공 응답만 보고 고정 링크 최신 상태를 확인하지 않음
- 모의 객체만으로 실제 플랫폼 계약 검증 완료 주장
- 기존 로컬 자료 자동 업로드·삭제
- 열쇠 문자열을 정적 HTML에 삽입
- 실제 항목 수를 확인하지 않고 29·14·4를 강제
- 단순 태그 개수만 같으면 HTML 정상이라고 판정
- `</script` 문자열이 없다는 것만으로 스크립트 안전 판정
- 새 판 재적재로 입력이 사라져도 성공 처리

---

## 16. 인터넷 공개 규칙

1. 외부 변경 전에 현재 로그인 계정·정확한 프로젝트·실제 쓰기 권한을 읽기 전용으로 확인한다.
2. 기존 대표 링크와 공개 범위를 유지한다.
3. 새 사이트·새 프로젝트·새 유료 DB·새 도메인을 자동 생성하지 않는다.
4. 프로젝트 필수 검사와 G0~G7을 통과한 뒤 공개한다.
5. 인터넷 공개 성공 표시뿐 아니라 대표 링크를 다시 열어 G8을 검증한다.
6. 공개 뒤 기존 사용자 자료가 자동 이전·삭제되지 않았음을 확인한다.
7. 심각한 자료 유실·권한 확대·링크 변경이 발견되면 새 쓰기를 중단하고 이전 정상판으로 안전하게 복구한다.

플랫폼 정책 때문에 사용자 확인 한 번이 필요하면 정확한 대상·변경·비용 0·URL 유지 여부를 보여 주고 그 한 번만 요청한다.

---

## 17. 산출물

1. 수정한 원본 빌더 또는 동등한 단일 원천
2. 재생성된 스코어카드 결과물
3. 공유 상태 자료 계약과 저장 어댑터
4. 권한·동시 편집·오프라인·이전 시험
5. 공개 대표 링크 또는 공개 보류의 정확한 이유
6. 저장 구조 선택 보고서
7. 이전·복구·운영 안내
8. 사용자가 받을 한 문단 설명

사용자 설명에는 다음을 솔직히 포함한다.

- 같은 링크에서 공유 최신 상태를 볼 수 있는 조건
- 편집 권한과 읽기 전용의 차이
- 로컬 초안은 다른 사람에게 보이지 않는다는 점
- AI는 사용자가 명시적으로 작업을 요청해야 움직인다는 점
- 동시 편집 충돌이 어떻게 처리되는지
- 실제로 사용한 저장 제공자와 아직 남은 제한

---

## 18. 최종 보고 형식

1. 결과: 완료/부분 완료/공개 보류
2. 감지한 프로젝트·빌더·대표 링크
3. 선택한 저장 구조와 선택 근거
4. 수정 파일과 핵심 변경
5. 권한 표: 소유자·편집자·뷰어의 읽기/쓰기
6. 저장 상태: 공유 저장·로컬 초안·오프라인·충돌
7. 기존 자료 이전 정책과 실제 실행 여부
8. 시험 결과: 정적·왕복·다중 사용자·권한·오프라인·공개
9. 기존 항목 수와 보존 결과
10. 공개 링크와 고정 링크 유지 여부
11. 실제 검증과 모의 검증의 구분
12. 변경하지 않은 것: 공개 범위·소유권·기존 사용자 자료·비용
13. 남은 위험과 정확한 오류 코드
14. 사용자가 다음에 할 단 하나의 행동

오류 코드는 최소 다음을 사용한다.

- `PROJECT_NOT_UNIQUE`
- `SHARED_STORAGE_UNAVAILABLE`
- `RUNTIME_API_UNVERIFIED`
- `EXTERNAL_ROLE_MISSING`
- `FIXED_LINK_WRITE_UNSUPPORTED`
- `CONFLICT_UNRESOLVED`
- `MIGRATION_CONFIRMATION_REQUIRED`
- `REAL_MULTIUSER_TEST_REQUIRED`
- `PUBLIC_VERIFICATION_FAILED`
- `COST_OR_NEW_RESOURCE_REQUIRED`

---

## 19. 종료 전 자체 검사

- [ ] 실제 계약을 읽지 않은 capability/API를 만들지 않았는가
- [ ] 앱 화면과 공유 상태를 분리했는가
- [ ] 고정 링크가 실제로 유지되는가
- [ ] 새 링크를 자동 우회로 만들지 않았는가
- [ ] 서버 또는 플랫폼에서 쓰기 권한을 강제하는가
- [ ] 저장 완료와 로컬 임시 저장을 구분하는가
- [ ] 판번호·조건부 쓰기·중복 방지가 있는가
- [ ] 같은 필드 충돌을 조용히 덮어쓰지 않는가
- [ ] 오프라인 대기 변경과 복귀 흐름이 있는가
- [ ] 기존 로컬 자료를 사용자 확인 없이 업로드·삭제하지 않는가
- [ ] 실제 항목 수를 코드에서 확인했는가
- [ ] 전체 HTML 재발행은 마지막 선택이며 모든 추가 조건을 통과했는가
- [ ] 모의 시험과 실제 다중 사용자 시험을 분리했는가
- [ ] 비밀값·개인정보가 코드·자료·로그·보고서에 없는가
- [ ] 공개 성공 뒤 실제 대표 링크를 다시 확인했는가
- [ ] 실패·미확인·미실시가 남았는데 완료라고 쓰지 않았는가

지금부터 G0부터 실행하라. 질문 전에 프로젝트와 공식 계약을 읽고 A~E 중 안전한 저장 구조를 선택하라. 확인 가능한 구현·시험·공개 준비는 계속 진행하고, 새 비용·새 외부 자원·새 링크·실제 사용자 자료 이전처럼 사용자 결정이 반드시 필요한 일만 한 번의 최소 질문으로 분리하라.


---

# 공통 안전 계약 — 권한·비용·인증·공개 안전 경계

원본 파일: `공통모듈_권한_비용_인증_공개_안전경계_v1.1.md`  
통합 시점 원본 SHA-256: `E67FF67BC7309D8DEED2FACE1396B2A9CB96D5D02036ECB2668F5AB98BFF3741`

> 이 공통 계약은 모든 모드에서 항상 활성화된다. 다른 엔진과 충돌하면 더 엄격한 증거·안전·완료 조건을 적용한다.

# 공통 모듈 — 권한·비용·인증·공개 안전 경계 v1.1

이 모듈은 안전 경계만 제공하며 그 자체로 외부 변경을 승인하지 않는다. 실제 사용자 요청·현재 권한·도구가 요구하는 실행 시점 확인이 대표 프롬프트의 작업 범위를 결정한다.

개발·로그인·호스팅·Sites·GitHub·공개 작업에 공통 적용한다.

## 기본 경계

- 프롬프트는 실제 권한·로그인·소유권·작업공간 구성원을 만들지 않는다.
- 외부 쓰기 전 현재 계정, 대상 자원, 실제 역할, 공개 범위, 비용을 읽기 전용으로 확인한다.
- 이메일·URL·프로젝트 이름에서 사용자 번호나 소유권을 추측하지 않는다.
- 편집자·방문자·관리자·소유자를 서로 바꾸어 보고하지 않는다.
- 비용 기본값은 0이다. 유료 좌석·플랜·체험·추후 청구를 자동 승인하지 않는다.
- 기존 URL·사용자·자료·접근 범위·판을 보존한다.
- 비밀번호·OTP·쿠키·개인 키·열쇠 문자열을 출력·저장하지 않는다.

## 공개 경계

- 저장판 생성과 인터넷 공개를 분리한다.
- 기존 공개 Site의 후속판은 기존 접근 범위를 보존한다.
- 도구가 공개 시점 확인을 요구하면 대상과 범위를 표시하고 한 번 확인받는다.
- 새 Site 생성은 공식 이전과 다르며 기존 ID·URL·자료가 자동 승계되지 않는다.
- 성공은 공식 상태 재조회와 실제 URL 검사로만 판정한다.

## 사용자 행동

AI가 대신할 수 없는 로그인·본인확인·비밀값 입력·비용·DNS·자료 이동만 한 동작으로 요청한다. 나머지 안전한 준비를 먼저 끝내고 중단 지점을 기록하여 그 지점부터 재개한다.