From 913abe33520447e9273a53e49b4128f7c28b1100 Mon Sep 17 00:00:00 2001 From: Samgu Lee Date: Tue, 6 Oct 2026 00:38:08 +0900 Subject: [PATCH 1/2] feat: refine TECH_STACK_DISCOVERY and TECH_STACK prompts for clarity and specificity --- .../prompts/TECH_STACK_DISCOVERY_PROMPT.txt | 269 ++++-------------- templates/prompts/TECH_STACK_PROMPT.txt | 84 +++--- 2 files changed, 108 insertions(+), 245 deletions(-) diff --git a/templates/prompts/TECH_STACK_DISCOVERY_PROMPT.txt b/templates/prompts/TECH_STACK_DISCOVERY_PROMPT.txt index bb21f53..e217302 100644 --- a/templates/prompts/TECH_STACK_DISCOVERY_PROMPT.txt +++ b/templates/prompts/TECH_STACK_DISCOVERY_PROMPT.txt @@ -1,213 +1,68 @@ -Assume PRODUCT_SPEC.md already exist and are correct. +Input: PRODUCT_SPEC.md only. It is correct and final. +ARCHITECTURE.md does not exist yet. It will be written AFTER TECH_STACK.md. + +PURPOSE +Discover every technology decision required to generate TECH_STACK.md. +Do NOT generate TECH_STACK.md. Do NOT generate code. + +SCOPE +- The goal is technology decisions. Architecture may be discussed ONLY to + the extent it constrains or drives a technology choice + (e.g. offline-first, server presence, realtime sync, single binary). +- Ask about architectural DRIVERS (requirements that affect the stack), + never about architectural SOLUTIONS (components, layers, module boundaries, + data flow, ownership boundaries). +- If I propose a structural idea, do not decide it. Record it as an ARCH NOTE + and continue. +- Directory, state, and dependency questions are limited to what the chosen + stack or framework mandates. + +PROCESS +- Ask one decision at a time. Wait for the answer before continuing. +- Never infer, assume defaults, or batch unrelated decisions. +- If PRODUCT_SPEC.md already answers a decision, mark it ALREADY DECIDED + with the quoted source line, and move on. +- If an area does not apply, mark it N/A with a one-line reason, and move on. +- Do not evaluate or recommend technologies. Exception: if I explicitly ask + for a recommendation on the current question, answer only that, then + return to discovery mode. +- If a later answer conflicts with a DECIDED item, stop and ask which one + wins before continuing. + +AREAS (in this order) +1. Platform (target platforms, runtime constraints, distribution targets) +2. Performance constraints (latency, throughput, memory) +3. Programming language +4. UI tech stack +5. Rendering (approach, graphics constraints) +6. State management (stack-level mutation model only) +7. Persistence (storage technology and requirements) +8. Dependency policy (external dependency rules only) +9. Testing (test types, coverage expectations) +10. Configuration (env separation, secret storage) +11. Logging (rules, sensitive information) +12. Security (secret handling, input validation) +13. Build (variants, constraints) +14. Deployment (targets, release environments) +15. Debugging / observability + +OUTPUT FORMAT for each question: -The purpose of this task is NOT to generate TECH_STACK.md. - -The purpose is to discover every implementation decision required to generate TECH_STACK.md. - -Do not infer missing decisions. - -Do not assume defaults. - -Do not recommend technologies unless explicitly asked. - -Do not generate TECH_STACK.md. - -Do not generate code. - -Do not evaluate alternatives unless explicitly requested. - ---- - -Your job is to identify implementation decisions that are still undefined. - -For each missing decision: - -- explain why the decision is required, -- explain which parts of the system depend on it, -- ask a question, -- wait for an answer. - -Do not continue past unanswered decisions. - -Do not batch unrelated decisions. - -Ask one decision at a time. - -Do not make assumptions. - ---- - -The discovery process must cover: - -## Platform - -Determine: - -- target platforms -- runtime constraints -- distribution targets - ---- - -## Programming Language - -Determine: - -- implementation language - ---- - -## UI Tech stack - -Determine: - -- user interface tech stack - ---- - -## Rendering System - -Determine: - -- rendering approach -- graphics constraints - ---- - -## State Management Style - -Determine: - -- state ownership model -- mutation model - ---- - -## Persistence - -Determine: - -- persistence requirements -- storage boundaries - ---- - -## Directory Structure - -Determine: - -- project organization rules -- ownership boundaries - ---- - -## Dependency Rules - -Determine: - -- external dependency policy -- dependency ownership - ---- - -## Testing - -Determine: - -- required test types -- coverage expectations - ---- - -## Configuration - -Determine: - -- configuration ownership -- environment separation rules - ---- - -## Logging - -Determine: - -- logging rules -- sensitive information rules - ---- - -## Security - -Determine: - -- secret handling rules -- input validation rules - ---- - -## Deployment - -Determine: - -- deployment targets -- release environments - ---- - -## Build Rules - -Determine: - -- build variants -- build constraints - ---- - -## Performance Constraints - -Determine: - -- latency requirements -- throughput requirements -- memory constraints - ---- - -## Debugging - -Determine: - -- debugging capabilities -- observability requirements - ---- - -Output format: - -```text MISSING DECISION +Name: +Reason: +Affected Areas: +Question: +WAITING FOR ANSWER -Name: - - -Reason: - - -Affected Areas: -- ... - -Question: - +After every answer, print both logs before the next question: -WAITING FOR ANSWER -``` +DECIDED +- : -Rules: +ARCH NOTES (non-binding, for ARCHITECTURE.md later) +- -- Ask only one question at a time. -- Never assume missing decisions. -- Never generate TECH_STACK.md. -- Never generate code. -- Never continue automatically. -- Wait after every answer. +COMPLETION +When all areas are resolved, print the final DECIDED log and ARCH NOTES, +then stop. Do not generate TECH_STACK.md. diff --git a/templates/prompts/TECH_STACK_PROMPT.txt b/templates/prompts/TECH_STACK_PROMPT.txt index 203a87d..d1752b5 100644 --- a/templates/prompts/TECH_STACK_PROMPT.txt +++ b/templates/prompts/TECH_STACK_PROMPT.txt @@ -1,40 +1,48 @@ Generate TECH_STACK.md. -Assume PRODUCT.md and architecture.md already exist and are correct. - -The purpose of TECH_STACK.md is to eliminate implementation ambiguity. - -TECH_STACK.md defines implementation constraints only. - -Do not infer undecided technologies. - -Do not assume technology decisions have already been made. - -If required decisions are missing, stop and ask questions. - -Do not evaluate alternatives. - -Do not recommend technologies. - -When a decision has already been made, encode it as a rule. - -When a decision has not been made, do not invent one. - -The document must include: - -- implementation rules -- architectural constraints -- directory structure -- testing rules -- deployment rules -- configuration rules -- security rules -- tech-stack-specific conventions -- non-goals -- architectural invariants - -Prefer explicit constraints over explanations. - -Optimize for implementation consistency. - -The document is intended for AI implementation, not human learning. +INPUTS +- PRODUCT_SPEC.md: correct and final. Source of product requirements. +- TECH_DECISIONS: correct and final. Sole source of technology names and versions. +- ARCHITECTURE.md does not exist yet. It will be written AFTER this document, using it as input. + +SOURCE RULES +- Every technology, tool, library, version, file name, and env var name MUST come from TECH_DECISIONS. +- MUST NOT infer, invent, evaluate, or recommend technologies. +- MUST NOT restate product behavior from PRODUCT_SPEC (commands, options, sorting, error cases). +- If TECH_DECISIONS conflicts with PRODUCT_SPEC, stop and list the conflicts. + +REQUIRED DECISIONS CHECK +Verify TECH_DECISIONS defines all of the following. For each missing item, ask one question. +- runtime + version +- language + compile/run method +- module system +- package manager + lockfile +- web framework + version +- libraries (name + version): config parser, CLI argument parser, YouTube API client/HTTP +- test tool + coverage threshold +- linter, formatter +- CI system +- deployment target + release/distribution method +- license +- config file format, env var names, secret storage +If any item is missing or conflicting: output ONLY the numbered question list. Nothing else. + +SCOPE BOUNDARY +- Cover only technology choices and the rules that follow from them. +- MUST NOT define components, layers, modules, boundaries, data flow, responsibilities, or system structure. +- MUST NOT define directory layout beyond paths mandated by the chosen framework or tooling. +- MUST NOT include process rules (change control), product non-goals, or architectural invariants. +- State each rule once. MUST NOT repeat a rule across sections. + +OUTPUT FORMAT +- Exactly these 8 sections, in this order, numbered headings, no other sections: + 1. Languages / runtimes / frameworks / libraries (name + version constraint) + 2. Framework- or tool-mandated paths and file names only + 3. Coding conventions specific to the chosen stack + 4. Testing rules (tools, naming, required coverage) + 5. Configuration rules (env vars, config files, secrets handling) + 6. Deployment rules (targets, build, release steps) + 7. Security rules tied to the chosen stack + 8. Non-goals (technologies and tools explicitly excluded) +- Flat terse bullets. "MUST / MUST NOT" phrasing. No prose, no explanations, no "why". +- Audience: AI implementer. From a51de526fff9d1cafffbd72d7a3c9c5412f18e01 Mon Sep 17 00:00:00 2001 From: Samgu Lee Date: Tue, 6 Oct 2026 00:38:16 +0900 Subject: [PATCH 2/2] feat: update showcase project test to expect 8 compatible cards --- tests/index.e2e.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/index.e2e.ts b/tests/index.e2e.ts index 59bd8fb..1c43584 100644 --- a/tests/index.e2e.ts +++ b/tests/index.e2e.ts @@ -171,7 +171,7 @@ test('loads the search interface', async ({ page }) => { test('shows all Showcase projects as compatible cards', async ({ page }) => { await page.goto('/showcase'); - await expect(page.locator('article a[href^="/showcase/"]')).toHaveCount(7); + await expect(page.locator('article a[href^="/showcase/"]')).toHaveCount(8); }); test('keeps primary pages within a mobile viewport', async ({ page }) => {