maxgfr/construct

construct — 제품 아이디어를 구축 가능한 SRD로 전환하기

construct는 제품 아이디어를 소프트웨어 요구사항 문서(SRD) 모음으로 전환합니다. 이 SRD의 요구사항과 결정은 모델의 메모리가 아닌 실제 조사에 기반합니다. 결정적 엔진(scripts/construct.mjs, 의존성 없는 Node)이 검색, 도큐멘트 수집, SRD 렌더링 및 검증을 코드로 수행합니다. 여러분의 역할은 인터뷰를 진행하고, 리서치를 주도하며, 렌더링된 뼈대를 정확하고 탄탄한 SRD로 보강하는 것입니다.

핵심 규칙: 추측된 요구사항보다 근거 있는 요구사항을 선호하세요. 엔진이 검색한 정보(경쟁사, 오픈소스 선례, 기술 문서, StackOverflow)를 사용하여 범위, 비기능 요구사항(NFR), 아키텍처 결정을 정당화하고, 증거를 [E#]로 인용하세요. 근거 제시는 권장 사항입니다. construct check 는 커버리지를 보고하지만 이를 이유로 실패하지 않으므로, 엄격함은 여러분이 적용해야 합니다.

스크립트

하나의 커밋된 의존성 없는 번들: node scripts/construct.mjs <command>. npm install 이나 API 키가 필요 없습니다. 전체 사용법은 --help를 참조하세요. 주요 명령어는 다음과 같습니다:

• init --idea "<한 줄 설명>" --out <run> — 실행 폴더 + brief.json 생성.
• research --out <run> [--angles market,oss,tech,semantic] [--q "<초점>"] [--semantic] — 여러 각도에서 증거를 수집하여 <run>/evidence/에 저장합니다([E#] ID가 있는 EVIDENCE.md + evidence.json 도큐멘트). 기본 각도: market,oss,tech.
• analyze --out <run> [--json] — "무엇이 부족한가?" 보고서: 현재 상태에서 근거 없이(UNGROUNDED) 렌더링될 모든 기능/경쟁사/기술/시드의 이름을 나열하고, 각 격차를 해결하는 드릴 명령어를 출력합니다. 정보 제공용이며 실행을 막지 않습니다.
• web|oss|tech|so --out <run> [--q "<초점>"] [--url ...] [--seeds ...] [--docs-url <u,...>] — 하나의 각도를 stdout으로 드릴다운합니다(도큐멘트 생성 안 함). 얇은 부분을 더 깊이 파고들 때 사용하며, --docs-url은 알려진 문서 페이지를 직접 근거로 사용합니다.
• render --out <run> [--level light|complex] [--merge] — brief.json + 도큐멘트에서 SRD 트리 + SRD.json을 렌더링합니다.
• check --out <run> [--min-grounding <0-100>] [--semantic] [--json] — 강제적 구조 게이트(불완전한 SRD에서 0이 아닌 종료 코드 반환) + 권고적 근거 커버리지 보고서. --min-grounding N은 N% 미만의 근거 있는 주장이 있을 경우 실패하는 두 번째 게이트를 활성화합니다. --semantic은 VERIFY.json(아래 review 참조)을 포함하고 반증/뒷받침되지 않는 주장이 있으면 실패합니다. (research --semantic과는 다릅니다. 후자는 임베딩 관련성에 따라 증거의 순위만 다시 매깁니다.)
• review --out <run> [--apply <verdicts.json>] [--max-review N] [--json] — 주장-뒷받침 도구. --apply 없이 실행하면 주장↔증거 작업 목록(VERIFY.todo.json + VERIFY.md)을 작성합니다. 근거가 있는 모든 주장과 인용된 각 [E#] 발췌문을 판단 대상으로 연결합니다. --apply <verdicts.json>은 여러분의 판정(supported|partial|refuted|unsupported)을 VERIFY.json으로 축약하며, check --semantic이 이를 게이트로 사용합니다. references/orchestration.md에 따라 여러 서브 에이전트에 분산할 수 있습니다.
• verify --out <run> [--app <dir>] [--run-tests] [--strict] [--json] — 빌드 심판: BUILD-PLAN.json이 잘 구성되어 있고 순환이 없으며, 모든 태스크 참조가 SRD.json에 존재하고, 완료된 태스크의 파일이 존재하며, 모든 요구사항이 테스트에 의해 참조되는지 확인합니다. --run-tests는 선언된 테스트 명령어를 실행합니다. --strict는 빌드된 'must-have'에 대해 참조하는 테스트가 없으면 실패합니다.
• status --out <run> [--json] — 현재까지 실행 폴더에 무엇이 있는지 표시합니다. --json은 빌드 프론티어(현재 빌드 가능한 BUILD-PLAN 태스크와 차단된 태스크)를 추가로 보여줍니다.
• semantic up|down|status — 선택적 로컬 Docker 스택(Qdrant + Ollama + SearXNG).

워크플로우

당신은 한 번 호출되어 완전하고 근거 있는 SRD를 반환해야 합니다. 완료될 때까지 루프를 실행하고, 진정한 결정이 필요할 때만 사용자에게 질문을 멈춥니다.

1. 사용자 인터뷰 — 한 번에 한 질문씩. 리서치 전에 제품을 확립하세요. references/interview-playbook.md를 따르세요: 문제, 대상 사용자, 핵심 가치, must/should/could 기능, 제약 조건(예산, 일정, 팀, 규정 준수), 후보 기술, 경쟁사/OSS 시드. 각 질문에 답변을 제안하고, 설문지를 던지지 마세요. 답변을 brief.json에 기록하세요(construct init으로 시작).

2. 리서치 — 아이디어에 근거를 더하세요. 다음을 실행하세요:

   node scripts/construct.mjs research --out <run> --angles market,oss,tech
   

   웹에서 경쟁사를 발견하고, 유사한 OSS 프로젝트(및 실제 문제점을 위한 해당 이슈/PR)를 마이닝하며, 후보 기술 문서 + StackOverflow를 가져옵니다. <run>/evidence/EVIDENCE.md를 읽으세요.

3. 더 깊이 파고들기 — analyze가 깔끔해지거나 사용자가 멈출 때까지. 다음을 실행하세요:

   node scripts/construct.mjs analyze --out <run>
   

   무엇이 얇은지 정확히 알려줍니다 — 일치하는 증거가 없는 기능, 경쟁사, 후보 기술 및 OSS 시드 — 그리고 각 격차를 해결하는 드릴 명령어를 출력합니다. 분산 처리: 병렬 서브에이전트를 생성할 수 있다면 격차당 하나씩 할당하세요. 각 서브에이전트는 간략한 한 줄 설명, 격차, 드릴 명령어 및 자체 웹 검색을 받고, 5줄 이하 요약과 근거가 될 URL을 반환합니다. 서브에이전트는 실행 폴더에 쓰면 안 됩니다. 드릴은 stdout으로 출력됩니다. construct research만이 도큐멘트를 작성하며, 오직 당신만이 그것을 실행합니다. 발견 사항을 직렬로 통합하세요: construct web --url <u,...> --out <run> → research 재실행 → analyze 재실행. (서브에이전트가 없으면 직접 격차를 하나씩 처리하세요.) 발견한 내용을 사용자에게 알리고 사용자가 방향을 정하도록 하세요 — must-have 기능과 중요한 결정에 우선순위를 두고, 사용자가 충분하다고 말하면 중단하세요. references/orchestration.md 및 references/research-playbook.md을 참조하세요.

4. SRD 렌더링. 브리프가 확실하고 도큐멘트가 풍부할 때:

   node scripts/construct.mjs render --out <run> --level complex
   

   빌드가 가능하다면 항상 complex를 선택하세요. 나중에 레벨을 전환하면 FR ID가 다시 번호가 매겨집니다(references/srd-authoring.md 참조). 이 명령어는 SRD 트리(아래 참조)를 작성합니다. 데이터 모델과 인터페이스는 브리프로부터 추론되어 미리 시드됩니다. 신뢰하지 말고 검증하세요. 그런 다음 보강하세요: 모든 🧠 Decide: 콜아웃을 해결하고, 템플릿화된 승인 기준과 NFR 메트릭을 테스트 가능하고 경계가 명확한 진술로 다듬고(references/acceptance-criteria.md 참조 — 템플릿이 남아 있으면 check가 경고), 데이터 모델과 인터페이스를 수정/확장하며, 도큐멘트의 [E#] 인용을 요구사항과 결정에 추가하세요. references/srd-authoring.md 및 references/citation-format.md 참조. complex 레벨에서는 디자인 시스템(design/)도 보강하세요: 시드된 디자인 토큰을 제품의 실제 브랜드 가치로 교체하고, 컴포넌트 및 화면/흐름 인벤토리를 확인하며, 접근성 기준을 대상 표준(브리프에서 파생, 기본값 WCAG 2.2 AA)으로 구체화하세요. references/design-system-authoring.md 참조.

5. 적대적 검토 — 새로운 시각으로 깨뜨리기. 실행 폴더 경로와 references/adversarial-review.md 만을 컨텍스트로 하여 검토자 서브에이전트를 하나 생성하세요(서브에이전트가 없으면 직접 적대적 독자로서 해당 체크리스트를 엄격히 따라 패스를 수행하세요). SRD를 깨뜨리려고 시도해야 합니다 — 모호함, 테스트 불가능한 기준, 누락된 실패 경로, 인용 세탁, 모순 — 그리고 태그된 발견 사항을 반환합니다. 모든 [blocker]를 수정하고 [advisory]는 판단을 사용하며, check를 다시 실행하세요. 새로운 차단 항목이 나타나지 않을 때까지 반복하세요(최대 3라운드, 이후 남은 것을 사용자에게 알립니다). complex 레벨에서 진정으로 논쟁이 있고 되돌리기 어려운 ADR의 경우, references/orchestration.md의 3-심사위원 패널도 실행하세요.

6. 검증 (세 가지 레이어).

   • 구조적 (강제): node scripts/construct.mjs check --out <run>. 해결되지 않은 🧠, 기능 요구사항(FR) 완전 부재, 승인 기준이 없는 FR, 연결이 끊긴 엔터티/인터페이스/NFR 참조, 누락된 필수 NFR 카테고리, 또는 잘못된 형식의 ADR이 있으면 실패합니다. 통과할 때까지 수정하세요.
   • 근거 제시 (권고): 동일한 명령어가 커버리지를 출력합니다 — 요구사항/결정 중 증거를 인용하는 비율입니다. 중요한 결정에서 커버리지를 높이세요. references/grounding-coverage.md 참조. 기본적으로 빌드를 실패시키지 않으므로 판단을 사용하세요. 사용자가 근거 제시를 강제하려면 옵트인 게이트를 추가하세요: check --out <run> --min-grounding 70.
   • 주장-뒷받침 (권고 → 옵트인 게이트): 커버리지는 인용 횟수를 세지만, 인용이 유효한지는 확인하지 않습니다. construct review --out <run>은 주장↔증거 작업 목록을 만듭니다. 각 쌍을 판단하고(references/orchestration.md 패턴 4에 따라 분산 처리), verdicts.json을 조합하고, review --apply verdicts.json을 실행한 다음, check --out <run> --semantic으로 반증/뒷받침되지 않는 주문을 게이트하세요. 제시 전에 중요한 FR/ADR을 한 번 통과시키는 것이 좋습니다. 단계 3~6을 check가 구조적으로 통과하고, 검토자가 새로운 차단 항목을 찾지 못하며, 근거 제시가 정직할 때까지 반복하세요.

7. 제시. 사용자에게 SRD 모음을 제공하세요: 비전, 경쟁 구도, 근거 있는 요구사항, 주요 결정(해당 [E#] 증거 및 링크 포함). 추측하는 대신 알려지지 않은 부분을 명시적으로 표시하세요.

8. 빌드 (사용자가 SRD뿐만 아니라 앱을 원할 때). 렌더링은 또한 BUILD-PLAN.json을 생성합니다 — 기계가 읽을 수 있는 태스크 DAG(T-000 스켈레톤 + FR당 하나의 태스크, must → should → could 순서, 엔터티 인식 종속성)로, acceptance 항목이 SRD.json을 가리킵니다. 모든 앱 코드는 당신이 작성합니다. 엔진이 심판합니다. references/build-playbook.md을 따르세요:

   • T-000(스캐폴드, 테스트 도구, CI)을 수행하고, BUILD-PLAN.json에 conventions.appDir 및 conventions.testCommand를 설정하세요.
   • 태스크당, 위상 순서로: SRD.json에서 승인 기준을 읽고, TDD로 개발하세요 — 모든 테스트는 FR ID를 지정합니다(예: describe("FR-001 …"). verify가 이것을 검색합니다.); artifacts + tests를 기록하고, status: "done"을 설정한 후, node scripts/construct.mjs verify --out <run>을 실행하고 다음 태스크 전에 오류를 수정하세요.
   • 같은 마일스톤의 태스크는 서로 간에 엣지가 없으므로, 준비된 프론티어(status --out <run> --json)를 병렬로 빌드할 수 있습니다 — 태스크당 하나의 격리된 git 워크트리; 당신만이 결과를 BUILD-PLAN.json에 통합합니다(references/orchestration.md의 패턴 5).
   • 마일스톤당: verify --out <run> --run-tests --strict를 실행한 다음, 마일스톤 적대적 검토를 수행합니다 — 새로운 시각으로 어떤 승인 기준도 실제로 테스트되지 않은 것을 찾습니다(플레이북 참조; references/verify.md는 verify가 증명할 수 있는 것과 없는 것을 설명합니다).
   • 빌드 중에 FR이 잘못된 것으로 판명되면, 브리프를 수정하고, 다시 렌더링하고(기능 제목으로 진행 상황 병합), 변경된 FR ID에 태그를 다시 지정하고, check를 다시 실행하세요.

산출물 (SRD 트리, --out 아래)

00-overview/   VISION.md · SCOPE.md (+ 🧠 열린 결정)
requirements/  FUNCTIONAL.md (FR-NNN · 우선순위 · Given/When/Then · [E#])
               NON-FUNCTIONAL.md (NFR-NNN by category · 메트릭 · [E#])
architecture/  SYSTEM-CONTEXT.md · DATA-MODEL.md · INTERFACES.md
               decisions/NNNN-*.md  (ADR)
design/        PRINCIPLES.md · DESIGN-TOKENS.md (+ design-tokens.json) · COMPONENTS.md
               SCREENS.md · ACCESSIBILITY.md      (complex 전용; --no-design으로 건너뛰기)
competitive/   LANDSCAPE.md (경쟁사 + OSS 선례)
BUILD-PLAN.md · BUILD-PLAN.json (빌드 단계를 위한 태스크 DAG)
TRACEABILITY.md (FR ↔ NFR ↔ ADR ↔ 엔터티 ↔ 인터페이스 ↔ 컴포넌트 ↔ 화면)
evidence/      EVIDENCE.md · evidence.json · meta.json   ·   brief.json · SRD.json

light는 간결하게 유지하고, complex는 전체 NFR 세트, 두 번째 ADR, 실패 경로 승인 기준, 전체 추적성 매트릭스 및 디자인 시스템 서브트리(design/: 원칙, 토큰, 컴포넌트, 화면/흐름, 접근성 계약 — --no-design으로 옵트아웃)를 추가합니다. 단일 파일 SRD.md를 위해 --merge를 추가하세요.

선택적 시맨틱 모드 (완전 로컬, API 키 불필요)

market/OSS/tech 각도는 네트워크 접근만 필요로 합니다. 수집된 증거에 대한 관련성 패스를 위해 로컬 임베딩 모델을 활성화할 수 있습니다:

node scripts/construct.mjs semantic up        # docker: Qdrant + Ollama + SearXNG
node scripts/construct.mjs research --out <run> --angles market,oss,tech,semantic --semantic

모든 것은 로컬 Docker 컨테이너에서 실행됩니다 — 키가 필요 없으며 데이터가 시스템을 벗어나지 않습니다. 스택이 실행 중이 아니면 --semantic은 공지사항을 기록하고 어휘 순위를 유지합니다. references/semantic-setup.md 참조.

참고 자료

• references/interview-playbook.md — 브리프를 한 번에 한 질문씩 이끌어내는 방법.
• references/research-playbook.md — 각도를 선택하고 "충분히 좋은" 수준까지 더 깊이 파고드는 방법.
• references/orchestration.md — 3계층 동적 워크플로우 모델 및 서브에이전트 패턴: 리서치 분산, 레드팀, 심사위원 패널, 주장-뒷받침 검토 분산, 빌드 분산(단일 작성자 규칙 포함).
• references/adversarial-review.md — 레드팀 체크리스트 및 발견 사항 계약.
• references/srd-authoring.md — 🧠 콜아웃 해결, 테스트 가능한 요구사항 및 ADR 작성.
• references/design-system-authoring.md — complex 디자인 시스템 보강: 토큰, 컴포넌트, 화면/흐름 및 접근성 계약.
• references/acceptance-criteria.md — 나쁜→좋은 Given/When/Then 재작성 및 측정 가능한 NFR 메트릭 패턴.
• references/citation-format.md — [E#] 근거 컨벤션.
• references/grounding-coverage.md — 권고 커버리지 보고서의 의미와 개선 방법.
• references/build-playbook.md — 빌드 루프: 태스크 TDD, FR 태그 컨벤션, 마일스톤 게이트, 마일스톤 검토.
• references/verify.md — 각 verify 검사가 증명하는 것과 여전히 사람의 눈이 필요한 것.
• references/provider-apis.md — 호스트별 OSS 이슈/PR을 키 없이 가져오는 방법.
• references/web-discovery.md — 계층화된 키 없는 웹 검색.
• references/semantic-setup.md — 선택적 로컬 Docker 스택.