git:20261012.aa46794 to git:20261029.9a25015

- description: 아직 모호한 제품/서비스 아이디어를 역질문과 선택지 제안으로 구체화해서, 다음 단계(PRD 작성)에 바로 쓸 수 있는 docs/IDEA.md 초안을 만든다. 사용자가 "앱 하나 만들고 싶은데", "이런 서비스 어때?", "아이디어 좀 같이 정리하자", "뭘 만들지 고민 중", "브레인스토밍" 같은 말을 하거나, 무엇을 만들지가 확정되지 않은 상태에서 기획/PRD/개발을 요청할 때 반드시 이 스킬을 먼저 사용한다. 요구사항이 흐릿한데 곧바로 코드나 문서를 쓰려는 상황이면 이 스킬로 먼저 범위를 좁힌다.

- ---

-

- # 아이디어 브레인스토밍 (Layer 0)

-

- ## 이 스킬의 목적

-

- 사용자가 가져오는 아이디어는 대부분 "한 문장"이다. 그 한 문장에는 만드는 사람이 결정해야 할 수십 개의 선택이 접혀 있다.

- 여기서 그 선택들을 펼쳐서, **PRD를 쓸 수 있을 만큼 구체화된 아이디어 정의서**(`docs/IDEA.md`)를 만든다.

-

- 중요한 전제가 하나 있다. 이 단계에서 잘못 좁힌 범위는 뒤의 모든 레이어(PRD → TRD → 아키텍처 → 플랜 → 태스크)에 그대로 복사된다.

- 그래서 여기서는 **빨리 답을 내는 것보다, 사용자가 스스로 답을 고르게 만드는 것**이 훨씬 가치가 크다.

- 추측으로 빈칸을 메우지 말고, 모르는 것은 물어본다.

-

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

-

- 이 스킬은 **문서 하나만 만든다.** 아래 것들은 손대지 않는다. 뒤쪽 레이어가 각자의 입력을 다시 검토해서 결정할 몫이기 때문이다.

-

- | 하지 않는 것 | 어디서 하는가 |

- |---|---|

- | 코드 작성, 파일 스캐폴딩 | Layer 5 개발 루프 |

- | 기술 스택·프레임워크·DB 선정 | Layer 1 TRD |

- | 데이터 모델, API, 화면 설계 | Layer 2 아키텍처 |

- | 주차별 일정 배분, 개발 순서 | Layer 3 마스터 플랜 |

-

- 이 경계가 중요한 이유가 있다. 여기서 "Next.js + Postgres로, 3주차에 인증"까지 적어 버리면, TRD와 플랜을 쓰는 단계에서

- 그것을 **검토 대상이 아니라 기정사실로** 읽는다. 검토 없이 통과한 결정은 나중에 태스크 수십 개를 되돌리게 만든다.

- 제약 조건(기간·인원)은 **적되**, 그 제약을 어떻게 소화할지에 대한 계획은 적지 않는다.

-

- 한편 사용자가 "그래서 뭘로 만들어?"라고 직접 물으면 대답은 해도 된다. 다만 **문서에는 넣지 말고**, "그건 TRD 단계에서 정합니다"라고 알린다.

-

- ### 이 스킬을 건너뛰어도 되는 경우

-

- 사용자가 이미 무엇을 만들지 확실히 알고 있고 문서화만 원한다면, 여기서 시간을 쓰지 말고

- "아이디어는 충분히 정리되어 있으니 바로 PRD로 가시겠어요?"라고 제안한다. Layer 0은 선택 단계다.

-

- ## 전체 흐름

-

- ```

- 1. 아이디어 성숙도 판정 → 2. 맥락 수집 → 3. 역질문 루프

- ↓

- 6. 다음 단계 인계 ← 5. docs/IDEA.md 작성 ← 4. 방향 2~3안 제시 및 선택

- ```

-

- `docs/IDEA.md` 가 이미 있으면 위 흐름을 돌지 않고 **7단계(부분 갱신)** 만 한다.

-

- ## 1단계. 아이디어 성숙도 판정

-

- 먼저 사용자의 말이 어느 수준인지 스스로 분류한다. 질문의 개수와 깊이가 여기서 결정된다.

-

- | 수준 | 예시 | 대응 |

- |---|---|---|

- | **씨앗(seed)** | "AI로 뭔가 만들고 싶어" | 문제 정의부터. 질문 6~10개, 방향 제안 필수 |

- | **윤곽(sketch)** | "프리랜서 계약서 관리 SaaS" | 사용자·범위·차별점 중심. 질문 4~6개 |

- | **구체(shaped)** | 기능 목록까지 들고 온 경우 | 빈칸과 모순만 확인. 질문 2~4개, 바로 IDEA.md |

-

- 사용자가 이미 많이 정해 놓았는데 처음부터 다시 캐묻는 것은 시간 낭비다. **이미 말한 것은 다시 묻지 않는다.**

- 반대로 씨앗 수준인데 질문 두 개로 끝내면, 사용자가 원하지 않는 제품을 만들게 된다.

-

- ## 2단계. 맥락 수집

-

- 질문하기 전에 스스로 확인할 수 있는 것은 확인한다. 사용자에게 이미 아는 것을 묻는 것만큼 신뢰를 깎는 일이 없다.

-

- - 현재 디렉터리에 코드베이스가 있는가? (`README.md`, `package.json`, `pyproject.toml` 등)

- - `docs/` 에 이미 `IDEA.md` / `PRD.md` 가 있는가? 있다면 읽고, 새로 쓰지 말고 **이어서 보완**한다.

- - 기존 프로젝트 위에 얹는 기능인지, 완전한 신규 프로젝트인지.

-

- 신규인지 기존 확장인지는 이후 모든 레이어의 형태를 바꾼다. 불확실하면 이것만은 반드시 묻는다.

-

- ## 3단계. 역질문 루프 — 이 스킬의 핵심

-

- ### 질문하는 방식

-

- - **한 번에 1~2개만 묻는다.** 질문 8개를 한꺼번에 던지면 사용자는 대충 답하거나 지쳐서 "알아서 해줘"라고 한다. 그 순간 이 스킬은 실패한다.

- - **모든 질문에 선택지를 붙인다.** "타깃 사용자가 누구인가요?"보다 "A) 1인 프리랜서 B) 5~20인 소규모 에이전시 C) 사내 법무팀 — 어느 쪽이 먼저인가요?"가 훨씬 좋은 답을 얻는다. 사용자는 백지보다 선택지에서 자기 생각을 훨씬 잘 발견한다.

- - **왜 묻는지 한 줄로 붙인다.** "결제를 붙일지에 따라 인증 구조가 달라져서요." 이유를 알면 사용자는 더 정확하게 답한다.

- - 사용자가 "몰라요 / 추천해줘"라고 하면 **되묻지 말고 추천안 하나를 근거와 함께 제시하고 확인만 받는다.** 판단을 떠넘기는 브레인스토밍은 도움이 안 된다.

- - 답이 나온 축은 다시 묻지 않는다. 답에서 파생되는 **다음 질문**으로 넘어간다.

-

- ### 반드시 채워야 하는 질문 축

-

- 아래 축이 모두 채워지면 PRD를 쓸 수 있다. 순서대로 갈 필요는 없고, 사용자의 답에서 자연스럽게 이어지는 축을 고른다.

-

- 1. **문제** — 누구의 어떤 불편인가. 실제로 겪은 일인가, 짐작인가.

- 2. **사용자** — 가장 먼저 쓸 한 명을 구체적으로 그릴 수 있는가.

- 3. **현재 대안** — 지금은 그 일을 어떻게 처리하고 있는가. (엑셀? 카톡? 경쟁 서비스?)

- 4. **핵심 가치** — 그 대안 대비 무엇이 명백히 나은가. 한 문장으로.

- 5. **핵심 흐름** — 사용자가 처음 들어와서 가치를 느끼기까지의 최단 경로.

- 6. **MVP 범위** — 첫 버전에 반드시 있어야 하는 것 / 없어도 되는 것.

- 7. **제약** — 기간, 예산, 혼자인지 팀인지, 반드시 써야 하거나 절대 못 쓰는 기술.

- 8. **성공 기준** — 무엇이 되면 "이거 되네"라고 말할 수 있는가. 가능하면 숫자로.

- 9. **리스크** — 이 아이디어가 실패한다면 가장 그럴듯한 이유는 무엇인가.

-

- ### 멈춰야 할 때

-

- - 사용자의 답끼리 **모순**될 때: 넘어가지 말고 짚는다. ("2주 안에 출시 + 실시간 협업 편집"은 같이 가기 어렵습니다. 어느 쪽을 먼저 두시겠어요?)

- - 답이 **추측 없이는 진행 불가**할 때: 임의로 정하지 말고 묻는다. 여기서의 임의 결정은 뒤에서 수십 개 태스크의 재작업이 된다.

- - 반대로 **사소한 선택**(문서 파일명, 예시 문구 등)은 묻지 말고 정하고 넘어간다. 질문 예산은 중요한 곳에 쓴다.

-

- ## 4단계. 방향 제안 2~3안

-

- 축이 어느 정도 채워지면, 같은 문제를 푸는 **서로 다른 방향**을 2~3개 제시한다.

- 하나만 제시하면 사용자는 그것을 검토하는 대신 그냥 승인한다. 비교 대상이 있어야 진짜 선택이 일어난다.

-

- 무엇을 놓고 비교할지는 1단계에서 판정한 성숙도에 따라 다르다.

-

- - **씨앗** — 제품 방향 자체를 비교한다. 무엇을 만들지가 아직 열려 있다.

- - **윤곽** — 제품은 정해졌으니 **MVP 범위와 진입 순서**를 비교한다. ("서명부터" vs "청구부터" vs "둘 다 얇게")

- - **구체** — 대안을 억지로 만들지 않는다. 대신 사용자가 정한 범위에서 **가장 위험한 가정 하나**를 골라, 그것이 틀렸을 때의 대안 경로를 한 문단으로 제시한다.

-

- 어느 경우든 **대안은 사용자에게 직접 보여주고 고르게 한다.** 문서 안에만 적어 두면 선택이 일어나지 않는다.

- 문서의 "검토된 대안 방향" 절은 선택이 끝난 뒤 기록용으로 채운다.

-

- 각 안은 이 형태로 짧게 쓴다. 길게 쓰면 읽지 않는다.

-

- ```

- ### A안. (이름) — 한 줄 요약

- - 형태: 무엇을 만드는가 (웹앱 / 챗봇 / CLI / 확장프로그램 …)

- - 첫 사용자: 누구

- - 핵심 기능 3가지

- - 강점:

- - 약점/리스크:

- - 대략 규모: (예: 화면 5개, 외부 연동 1개, 사용자 역할 2종)

- ```

-

- 규모는 **크기**로 적고 기간으로 적지 않는다. "4~6주" 같은 숫자는 근거 없이 나오는데 뒤 레이어가 그것을 합의로 읽고,

- 플랜은 애초에 일정을 만들지 않는다(실행 주체가 한 태스크에 한 세션을 쓰는 에이전트라 기간이 아무것도 조정하지 못한다).

-

- 세 안은 **서로 다른 축에서 달라야 한다.** (예: 범위를 줄인 안 / 타깃을 바꾼 안 / 형태를 바꾼 안)

- 셋 다 비슷하면 선택지를 준 게 아니라 선택지를 준 척한 것이다.

-

- 마지막에 **추천안 하나와 그 이유**를 밝힌다. 사용자는 조합("A의 범위 + B의 타깃")을 고를 수도 있고, 그것도 좋은 결과다.

-

- ## 5단계. `docs/IDEA.md` 작성

-

- 방향이 정해지면 파일을 쓴다. 경로는 프로젝트 루트 기준 `docs/IDEA.md`.

- 이 파일은 다음 스킬(`prd-generator`)의 **유일한 입력**이므로, 대화에서 합의된 내용이 여기 빠지면 그대로 사라진다.

-

- ### 확정된 것과 가정한 것을 구분한다

-

- 문서를 쓰다 보면 사용자가 답하지 않은 칸이 반드시 남는다. 그 칸을 조용히 그럴듯한 값으로 채우는 것이 이 단계에서 가장 흔하고

- 가장 비싼 실수다. 뒤 레이어는 문서에 적힌 것을 전부 "합의된 것"으로 읽기 때문에, 가정이 사실로 승격된 채 아키텍처와 태스크까지 내려간다.

-

- 그래서 표기 규칙을 하나 둔다. 사용자가 직접 말하지 않은 값은 **문장 끝에 `(가정)` 을 붙이고**, 그 근거와 "틀렸을 때 무엇이 바뀌는지"를

- '주요 리스크와 가정' 표에 한 줄로 남긴다. 별도의 가정 절을 새로 만들 필요는 없다 — 표 하나로 충분하고, 흩어 놓으면 오히려 놓친다.

-

- 가정이 문서의 결론을 통째로 바꿀 만한 것이라면(예: "외부 API로 데이터 전송이 가능하다") 표에만 두지 말고

- **미결 사항 맨 위로 올린다.** 사용자가 가장 먼저 봐야 할 것이 그것이다.

-

- 아래 구조를 그대로 사용한다.

-

- ```markdown

- # 아이디어 정의서: (제품 이름 또는 가칭)

-

- - **버전**: 0.1

- - **변경 이력**: (없음 — 뒤 레이어가 범위를 바꾸면 `0.2 (YYYY-MM-DD, <스킬>) — <무엇을 왜>` 한 줄씩)

-

- ## 한 줄 정의

- (누구를 위해, 어떤 문제를, 어떻게 푸는지 한 문장)

-

- ## 문제

- - 현재 상황:

- - 불편의 구체적인 장면:

- - 지금의 대안과 그 한계:

-

- ## 타깃 사용자

- - 1순위 사용자:

- - (있다면) 2순위 사용자:

- - 쓰지 않을 사람 / 노리지 않는 시장:

-

- ## 핵심 가치 제안

- (대안 대비 명백히 나은 점 1~3개)

-

- ## 핵심 사용자 흐름

- 1.

- 2.

- 3.

-

- ## MVP 범위

- ### 포함

- -

- ### 제외 (다음 버전 이후)

- -

-

- ## 제약 조건

- - 기간:

- - 인원:

- - 기술적 제약 / 선호:

- - 예산·운영:

-

- ## 성공 기준

- - 정량:

- - 정성:

-

- ## 주요 리스크와 가정

- | 리스크/가정 | 근거 | 틀리면 무엇이 바뀌나 | 확인 방법 |

- |---|---|---|---|

- | | | | |

-

- ## 검토된 대안 방향

- - (선택하지 않은 안과 그 이유. 나중에 방향을 되돌릴 때 이 기록이 결정적으로 쓰인다.)

-

- ## 미결 사항

- - (아직 정하지 못한 것. PRD 단계에서 반드시 결정해야 함.)

- ```

-

- **미결 사항 칸을 비워 두려고 억지로 채우지 않는다.** 모르는 것을 아는 척 적는 것보다, "이건 아직 미정"이라고 남기는 편이 뒤 레이어에 훨씬 안전하다.

-

- ### `CLAUDE.md` · `AGENTS.md` 갱신

-

- `docs/IDEA.md` 를 쓴 뒤 프로젝트 루트의 `CLAUDE.md` 와 `AGENTS.md` 를 **같은 내용으로** 갱신한다. 사용자가 직접 연 세션과 루프의 자식 세션은 이 스킬을 읽지 않고 시작하는데,

- 그때 자동으로 읽히는 파일은 Claude Code 는 `CLAUDE.md`, Codex 는 `AGENTS.md` 뿐이다. 그래서 **지금 어느 호스트에서 돌든 둘 다 쓴다** —

- 한쪽만 쓰면 다른 호스트의 세션이 규칙을 모른 채 시작한다. 내용은 **어느 세션에서든 반드시 지킬 것**만 두고 세부 규칙은 문서를 가리킨다 —

- 규칙을 옮겨 적으면 두 곳이 곧 어긋나고, 어긋나면 세션은 짧은 쪽을 믿는다.

-

- - 둘 다 없으면 아래 뼈대로 만든다. 있으면 **`현재 단계` 줄만** 고친다. 다른 절과 사용자가 손으로 적은 내용은 건드리지 않는다

- - 두 파일이 서로 다르면 지금 호스트의 파일을 기준으로 다른 쪽을 맞춘다. 손으로 적은 줄은 양쪽에 남긴다

- - 파일은 있는데 `## 문서 지도`·`## 공통 규칙` 이 없으면(예: `/init` 이 만든 파일) 기존 내용 **아래에** 뼈대 두 절을 더한다. 기존 내용은 손대지 않는다

- - 전체 **100줄 안팎, 200줄을 넘기지 않는다.** 넘치면 규칙을 문서 쪽으로 돌려보내고 가리키는 줄만 남긴다

- - 이 스킬은 절을 두지 않는다 — IDEA.md 는 PRD 가 덮는다. 두 파일에 뼈대를 만들고 `현재 단계` 를 `idea-brainstorm → 다음: prd-generator` 로 적는 것이 전부다

-

- ```markdown

- # <프로젝트 이름>

-

- > harness-loop-fullstack 스킬이 만들고 갱신하는 파일이다. 각 절은 그 레이어의 스킬만 고친다.

- > `CLAUDE.md` 와 `AGENTS.md` 는 같은 내용이다. 한쪽을 손으로 고치면 다른 쪽도 같이 고친다.

- > 세부 규칙은 각 문서에 있다 — 여기에는 어느 세션에서든 반드시 지킬 것만 둔다. 200줄을 넘기지 않는다.

-

- ## 문서 지도

- - `docs/IDEA.md` → `docs/PRD.md` → `docs/TRD.md` → `docs/ARCHITECTURE/` → `plan_setup/` → `harness_setup/` → `loop_setup/LOOP.md`

- - 뒤 문서는 앞 문서를 근거로 한다. 어긋나면 앞 문서가 이긴다 — 바꿔야 하면 사용자 확인 뒤 **가장 앞 문서부터** 고치고(버전·`변경 이력` 한 줄. 프로젝트 완료 뒤에는 `feature-add`·`refactor-plan` 의 후미 절로) 사이 문서를 맞춘 다음 이어 간다(변경 전파). 손으로 고칠 때도 같다. 루프 세션은 앞 문서를 고치지 않고 LOOP.md 대로 멈춘다

- - 현재 단계: <마지막으로 끝낸 스킬> → 다음: <다음 스킬>

- ## 공통 규칙

- - 앞 레이어의 **파일**만 입력이다. 대화 기억이나 추측으로 요구사항·기술 결정을 만들지 않는다

- - ID(`FR-`·`NFR-`·`US-`·`OQ-`·`TD-`·`phase-NN-task-MM`)는 참조만 한다. 새 ID 는 마지막 번호 다음으로만 만든다 — OQ 는 프로젝트 전체(`HARNESS.md`·`LOOP.md` 의 미결 표까지)에서, 나머지는 그 문서에서 센다(변경 전파로 앞 문서에 더할 때도)

- - 사용자가 말하지 않은 값은 `(가정)` 으로 표시한다. 모호하면 추측하지 말고 묻는다

- - 요청된 범위를 조용히 넓히거나 줄이지 않는다. 범위 판단은 보고한다

- ```

- ## 6단계. 자체 점검 후 인계

- 파일을 쓴 뒤 처음부터 다시 읽으면서 확인한다. 통과 조건을 그대로 적었으니 방향을 헷갈리지 않는다.

- | 확인할 것 | 통과 조건 | 걸렸을 때 |

- |---|---|---|

- | 범위 | 기술 스택·데이터 모델·화면 설계·주차별 일정이 문서에 0건 | 지우고 "뒤 레이어 몫"이라고 알린다 |

- | 가정 표기 | 사용자가 말하지 않은 값에 전부 `(가정)` 표기 | 붙인다 |

- | 미결 | 억지로 채운 칸이 없고, 모르는 것은 미결로 남아 있음 | 확정한 척한 칸을 미결로 되돌린다 |

- | 대안 | 2~3안이 서로 다른 축에서 갈리고, 사용자에게 직접 제시됨 | 문서에만 있으면 응답에도 낸다 |

- | 다음 입력 | PRD를 쓸 수 있을 만큼 채워짐 (문제·사용자·범위·성공 기준) | 빈 축을 사용자에게 묻는다 |

- | `CLAUDE.md` · `AGENTS.md` | 두 파일이 같고 `현재 단계` 줄이 갱신됐고 각 200줄 이하 | 자기 절만 고친다. 넘치면 규칙을 문서로 돌려보내고 가리키는 줄만 남긴다 |

- **임의로 고쳐도 되는 것과 보고할 것이 다르다.** 형식 문제(가정 표기 누락, 범위를 넘은 서술)는 고치면 된다.

- 범위 판단(무엇을 MVP에 넣을지)은 사용자의 결정이므로 고치지 말고 보고한다.

- 그다음 사용자에게 이렇게 정리해 준다.

- 1. `docs/IDEA.md` 를 만들었다는 사실과 핵심 요약 3줄

- 2. 미결 사항이 있다면 그 목록

- 3. 다음 단계 안내: "이대로 PRD를 만들까요? (`prd-generator` 스킬)"

- 사용자가 확인하기 전에 임의로 PRD 작성으로 넘어가지 않는다. 아이디어 문서는 사람이 한 번 읽고 고치라고 만드는 것이다.

- ## 7단계. 이미 `docs/IDEA.md` 가 있을 때 — 부분 갱신

- 뒤 레이어(PRD·TRD·아키텍처·플랜)를 쓰다 보면 **범위가 바뀌는 결정**이 나온다 — MVP 에서 빼기로 한 기능, 새로 넣은 타깃, 바뀐 핵심 흐름.

- 그 결정이 IDEA.md 에 안 돌아오면 IDEA 와 PRD 가 서로 다른 제품을 말하고, 다음에 이 문서를 연 사람(또는 `feature-add`)은 옛 범위를 기준으로 판단한다.

- 그렇다고 1~6단계를 다시 돌리면 사용자와 고른 방향과 미결이 초기값으로 덮인다. `docs/IDEA.md` 가 이미 있으면 **이 단계만 한다.**

- - **범위에 닿는 것만 고친다** — 한 줄 정의·타깃 사용자·핵심 흐름·MVP 포함/제외·성공 기준. 그 밖의 세부는 PRD 가 덮으므로 여기 옮기지 않는다

- - 해당 줄만 고치고, 빠진 항목은 지우지 않고 `제외 (YYYY-MM-DD, <근거 문서·ID>)` 로 표시한다

- - 해소된 미결은 지우지 않고 "해소 — (무엇으로)" 로 바꾼다. `prd-generator` 가 이 목록을 OQ 로 승격시켰으면 PRD 쪽이 원본이다

- - **버전을 올리고 `변경 이력` 에 한 줄** — `0.2 (YYYY-MM-DD, <부른 스킬>) — <무엇을 왜>. 영향: <PRD 의 ID>`

- - 범위 결정 자체는 사용자가 한다. 이 단계는 **이미 내려진 결정을 기록**하는 일이다 — 결정이 아직이면 3단계처럼 묻는다

- 뒤 스킬이 이 단계를 부른 경우(변경 전파)에는 끝나면 그 스킬로 돌아간다. 보고에는 바뀐 줄과 새 버전만 적고, `CLAUDE.md` 의 `현재 단계` 줄은 건드리지 않는다.

- `feature-add` 가 후미 절 모드로 불렀으면 그 지시가 우선이다 — 본문을 고치지 않고 `## 추가 N` 절에 적는다(Layer 6 후미 절 모드면 `변경 이력` 줄은 쓰지 않는다 — 후미 절 첫 줄(날짜·요청)이 이력이다. 버전 줄은 이미 있을 때만 올리고, 없는 옛 IDEA.md 면 머리를 건드리지 않는다).

- 사용자가 직접 불러 범위를 바꿨고 `docs/PRD.md` 가 이미 있으면(프로젝트가 완료됐으면 — `Phase Overview` 전부 `completed` — 이 단계가 아니라 `feature-add` 다), 끝나고 `prd-generator` 8단계를 부른다 — 그 뒤 문서(TRD·아키텍처·플랜·하네스·루프)는 PRD 8단계의 "뒤 문서 맞추기" 순서대로 이 세션이 이어 부른다(연쇄는 처음 시작한 스킬 하나가 한다).

- ---

- ## 에이전트별 참고

- - Claude Code에서 실행 중이면: `references/claude-code.md`

- - Codex에서 실행 중이면: `references/codex.md`

- 공통 절차는 위 본문이 전부이고, 위 파일들은 질문을 주고받는 방식의 차이만 다룬다. 해당 환경이 아니면 읽지 않아도 된다.