Project Blueprint

把模糊的产品想法转化为人和编码代理都能执行、复核和持续维护的项目约束。重点不是多写文档，而是在开始实现前暴露假设、消除冲突、记录取舍，并让产品需求、行为规格、设计、架构、部署和测试能够互相追溯。

行为原则

采用 Karpathy-inspired 社区规则所总结的四个方向，但不要声称该文件由 Andrej Karpathy 编写：

先澄清再实现：明确假设、歧义和取舍，不替用户静默决定高影响事项。
简单优先：选择满足已知约束的最小方案，不为想象中的未来预建复杂度。
控制范围：只更新与蓝图直接相关的文档和设计确认预览；不顺手重写业务代码、配置或无关说明。
目标可验证：把“做一个功能”转化为可观察行为、验收场景和可运行的质量门禁。

所有产物还要遵守一条编辑原则：只写能改变决定、实现或验收的内容。删除聊天式开场、宣传性形容词、机械排比和无依据的完整感；不要用格式、装饰或篇幅冒充清晰度。

草案可以包含未知项，但不能把假设写成事实。所有未决项都要显式影响就绪度。

边界

支持绿地项目为主，也可读取已有 PRD、设计稿、代码仓库和部署材料进行补全。
支持 Web、SaaS、API、原生移动端和跨端应用。
生成或更新规范文档、机器可读接口契约、ADR、编码代理适配文件，以及用于人工设计确认的轻量 HTML 或已有项目内预览；预览只使用示例数据和局部演示交互，不生成业务代码、测试实现、运行中的 mock 服务或完整脚手架。
PRD.md 管立项与产品意图，根 SPEC.md 管分层索引与交付追踪，领域 spec 管可观察行为，接口 spec 管跨边界契约，任务 spec 管实现交接，DESIGN.md 管体验，ARCHITECTURE.md 管内部实现，SECURITY.md 管控制，DEPLOY.md 管运行环境。不要跨文档复制同一事实。
正文跟随用户语言；文件名、需求 ID、技术标识和代码符号保持英文。

开始前读取

每次都读取：

references/intake-and-status.md：访谈顺序、四态决策和就绪度闸门。
references/artifact-contract.md：文档职责、权威关系、ID 和追踪规则。
references/output-quality.md：所有蓝图产物的编辑质量、反模板化写作和 Emoji 默认规则。

按任务读取：

拆分功能、AC、接口或实现任务，以及审计 spec 覆盖与变更时，读取 references/spec-decomposition.md。
需要技术选型或中间件判断时，读取 references/selection-rubric.md。
需要 UI、移动端或系统设计时，读取 references/design-and-architecture.md；需要推荐、比较或确认应用骨架、导航和工作区布局时，同时读取 references/layout-catalog.md；需要推荐、比较或落地视觉主题时，同时读取 references/theme-catalog.md。
用户提供设计网站、截图、外部 DESIGN.md，或需要参考案例来收敛风格时，读取 references/design-reference-workflow.md：参考筛选、来源判断、特征转译及设计规范与预览的一致性。awesome-design-md 是可选案例入口，不是固定主题菜单或项目设计权威。
项目包含 Web 前端、交互式客户端或已有界面审计时，读取 references/frontend-companion-skills.md，按阶段使用已安装的伴随 Skills；React/Next.js 专属规则只能在确认技术栈后启用。
需要安全、部署、上线或运维约束时，读取 references/security-and-deployment.md。
目标市场涉及中国大陆、跨境/全球，或项目包含 AI/LLM 时，读取 references/regional-and-ai.md。
需要说明方法依据或核对稳定原则时，读取 references/sources.md。

输出时使用 assets/templates 中相应模板。不要一次性把所有参考文件读入上下文；先识别项目分支，再按需加载。

工作方式

0. 探索现状

在提问前先做只读检查：

找出已有 PRD.md、SPEC.md、DESIGN.md、架构/安全/部署文档、ADR、README、包清单、容器和 CI 配置。
若已有代码，识别实际客户端、语言、框架、数据存储、外部服务、测试和部署事实。
建立“已有事实 / 用户声明 / 合理推断 / 未知”四类信息；推断不能直接升级为已确认。
同名文档存在时，先生成冲突和拟变更摘要。经用户确认后增量修改，不静默覆盖或整篇重写。

1. 确认项目画像

从已有材料提取，缺失时分批询问：

用户、问题、核心任务、MVP、非目标和成功指标。
Web/移动端范围、目标市场、时间、预算、团队规模与技能。
数据敏感度、登录/支付/AI/实时/离线/第三方集成等条件分支。
流量、数据量、延迟、可用性、恢复目标及运维能力；未知时记录 TBD，不编造数字。

不要把整张问卷一次抛给用户。每轮只问会改变下一阶段或阻断结论的问题，并提供有取舍的候选和推荐默认。

选择检查点：产品、技术架构、UI 方向分别确认

产品访谈结束后，检查技术架构和 UI 方向是否各有适用于当前项目的用户选择或明确代选授权。确认 MVP、团队规模或部署地区不等于确认技术栈；允许生成蓝图不等于允许代选。没有方向时，分别在对话中展示技术候选与 2–3 个 UI 方向（布局、明暗、色彩与排版气质），说明推荐和代价，再请用户选择或授权代选。只把比较表写入文件不算完成选择环节。

等到回答后再锁定相应方案、生成依赖它的实现约束或声明相关任务 ready；等待期间可继续整理产品行为和无关文档。已有明确选择不重复询问；“继续”只承接当时明确展示的下一步，不补足从未提出的选型问题。用户要求不追问/直接出草案时，按要求交付 provisional 建议及待决定项；只有明确授权代选才能记为代理受托决定，不能伪称用户亲自评审。决策来源、授权范围和就绪度处理见访谈与状态规则。

2. 建立或审计 PRD

已有 PRD：保留其产品意图，只补缺失、冲突和不可验收之处。
没有 PRD：生成精简但可执行的 PRD.md，覆盖目标、角色、核心流程、MVP/非目标、功能需求、验收标准、指标、约束和风险。
为确认范围内的产品需求分配稳定 ID：PRD-<DOMAIN>-NNN。
PRD 立项章节作为 charter 来源：记录问题、目标、范围/非目标、可行性假设、外部约束与继续/调整条件；链接现有可行性材料，不另写一份重复 charter。PRD 说明“为什么/为谁/做什么”，不提前锁定内部技术实现。

3. 分层拆解规格与验收

新蓝图在根 SPEC.md 标记 spec_schema: 2。根文件只维护全局规则、分层索引、当前交付范围、依赖与追踪；每层链接权威来源，不复制正文。旧蓝图无版本字段时保留旧检查，迁移需明确增量变更，不能静默改写历史。

全景与近期细化：先列出 MVP 能力与依赖，再选近期交付范围。按业务边界、独立验收、接口边界拆分；优先可验收的纵向任务，不按文件、函数或固定工时机械拆分。远期任务只写目标、来源、依赖、风险及细化触发点。
功能 spec：小领域保留 specs/<domain>.md，复杂领域可按能力拆为 specs/<domain>/<capability>.md。每条 SPEC-<DOMAIN>-NNN 明确来源 PRD、角色、触发条件、输入约束、业务规则、状态变化与结果。功能 spec 不承载框架、数据库或内部算法；必要机制由架构/任务 spec 说明。
独立 AC：每条 AC-<DOMAIN>-NNN 属于一个功能 SPEC，用 Given/When/Then 描述可观察结果，明确测试数据/环境、断言、步骤/命令、预期证据与验证方式（automated/manual/hybrid）。按相关性覆盖失败、边界、权限、重复操作、并发、部分成功和恢复。未知阈值登记 TBD，不用“正常工作”替代断言。
接口 spec：按需要建立 specs/interfaces/，为跨模块/进程边界定义 IFACE-<DOMAIN>-NNN，关联功能与提供方/消费方。已确认协议按官方来源生成或复用 contracts/ 下 OpenAPI、protobuf 或 JSON Schema，机器契约是字段/线格式的唯一来源；Markdown 解释业务语义和兼容规则。协议未定时保留阻断项，不伪造完整契约。
任务 spec：在架构与接口已足够明确后，为近期工作在 specs/tasks/ 生成每个工作包一份 TASK-<DOMAIN>-NNN 规范。列出来源 SPEC/AC、接口、依赖、目标/非目标、变更范围、必要实现约束、测试与完成条件。只锁定正确性、兼容性和协作所需决定，局部编码选择留给实现代理。

模板与机器字段见拆解与验收契约。所有 AC 可判定不等于都能自动判定；人工业务验收和视觉认可有明确负责人。验证方式与执行结果分离，未执行记 not-run，passed 必须有证据、被测版本和执行日期。

4. 确认方向，生成预览，再固化设计

DESIGN.md 随设计成熟度逐步补充。使用 frontmatter design_stage: direction / prototype / specification / not-applicable，它与 confirmed/provisional/pending 等决策状态独立。默认从 direction 开始；已有认可的设计系统或样稿时复用适用证据，不强迫重新探索。纯 API 且无用户界面的项目使用 not-applicable 并说明理由。

direction：风格构思与关键定制。 确定受众、核心任务、信息架构和功能硬约束；围绕整体风格、参考中借鉴的特征、appearance、density、品牌色方向、字体层级与视觉重点收敛。用户明确“苹果官网风格”“企业深色工作台”等方向时直接细化，不强制重新比较；没有方向时给 2–3 个可信候选与主推荐，不用加权分数制造确定性。theme family 是描述词，不要求落入目录。无需填写完整色值、组件尺寸或状态参数。
prototype：生成预览与人工确认。 方向选定或已明确授权代选后，默认生成 design/preview.html，包含项目常用组件及重要状态、一个使用真实或明确标注示例内容的代表性业务页面，支持简单交互与桌面/窄屏查看。已有前端项目可复用预览路由；原生端可提供适用的可查看原型。先交付查看入口、版本和待确认重点，再请用户或指定设计负责人评审并按反馈调整，回收证据、评审人、日期、版本、确认范围和结论。方向认可和代理自检不能代替人工视觉确认。用户明确只要文档、工具不可用或已有适用认可证据时，记录交接或复用依据；细则见设计指导。
specification：从认可设计提取实现规范。 仅在视觉确认后补入实现规范补充模板的适用章节，仍以 DESIGN.md 为权威入口。统一记录配色、排版、空间/动效 token 来源及组件差异，允许链接已有设计系统或主题文件；不要求每个组件重复完整字体栈和数值。实现所需决定必须可追溯，不能用无来源的“品牌色/系统默认”代替。

区分功能硬约束、已确认品牌要求和可探索视觉建议。构思时保留字号、留白、圆角、阴影和组件外观的探索空间；确有既定品牌数值则保留。紧凑列表不意味着全页紧凑，文档语言克制不意味着视觉必须素白、中性或禁止品牌表达。参考选择要说明借鉴什么、哪些特征不适合当前任务，不只给网站名加一个主色。

参考驱动的设计要形成可追溯链：来源与适用页面 → 借鉴/调整/排除 → 本项目的视觉主张与使用边界 → 预览中的验证位置 → 认可后的 token、组件规则和实现交接。外部分析中的精确数值仍是待验证参考，不自动成为已确认设计；官网、工作台和原生端分别判断。DESIGN.md 用简短视觉主张说明核心任务如何影响层级、排版和表面关系，并记录少量有依据的“采用/避免”规则。实现阶段给出链接到认可版本、共享 token 与组件规则的代理交接说明，避免下游重新猜风格。

布局仍区分 layout family、navigation model、work-surface model 和 platform chrome；SSO、身份或租户切换不直接决定侧边栏。方向阶段说明空间关系和内容优先级，精确几何留待样稿验证。

React、Vue 等交互型客户端在进入交互原型时选择一致的 UI 基础；已有明确技术选型可提前记录。正式实现前确认主题入口、复杂组件覆盖、图标、无障碍、维护责任及官方兼容性依据。可评估 shadcn/ui、shadcn-vue 等开放代码/headless 体系或适用的完整组件套件；不要把浏览器未主题化的原生控件或组件库默认皮肤当作成品设计。按需读取设计指导中的 UI 基础规则，不让组件库外观反向决定风格。

伴随 Skills 按阶段路由：ui-ux-pro-max 辅助候选与 UX 检索，frontend-design 辅助方向、构图、预览制作及样稿评议，web-design-guidelines 审查已有界面，vercel-react-best-practices 仅用于已确认 React/Next.js 的实现约束。轻量预览属于本技能交付范围；超出该范围的完整原型另行交接，结果回收到蓝图。缺少伴随 Skill 不阻止生成预览；无法制作或查看时明确缺口，不虚构验证通过。

详见设计指导的阶段规则和证据格式。保留响应式、状态矩阵、内容、图标/图像/Emoji 与无障碍要求；早期缺少视觉细节不阻断原型探索，未完成视觉确认则不能宣称可按定稿批量实现。

5. 确认架构、安全与部署

ARCHITECTURE.md：上下文与容器视图、模块边界、数据所有权、API/事件契约、存储、集成、中间件决策、质量属性预算和演进阈值。
SECURITY.md：数据分类、信任边界、认证授权、隐私、密钥、依赖/供应链、安全验证和事件响应。
DEPLOY.md：环境矩阵、区域与服务、构建物、配置/密钥、CI/CD、数据库变更、发布/回滚、观测、备份、RTO/RPO、域名证书、移动商店与成本护栏。

每次做全栈技术选型时，候选表必须先包含以下三套固定参考栈，再根据项目约束追加更合适的候选：

企业级项目：Java Spring Boot + React。
工具型项目：Python FastAPI + Vue SPA。
简单快速项目：Python Flask + Jinja SSR。

固定展示不等于固定推荐。逐套说明与当前团队、交付周期、交互复杂度、集成、安全和部署约束的匹配点与缺口；明显不适用时保留该行并标记“不推荐”，不能静默删除。最终从固定栈和分析追加项中推荐一套；证据不足时给 provisional 建议或保持 pending。

在对话中把推荐栈、架构形态、主数据库和部署方式作为可评审方案展示，允许用户整体采用或修改其中一项；不要要求用户逐个决定局部实现细节。按选择检查点取得回答后，再把适用选择记为 confirmed 并生成依赖该方案的近期任务。

架构默认从模块化单体、关系型数据库和合适的托管服务开始。只有需求、指标或团队边界证明必要时，才引入缓存、消息队列、搜索引擎、微服务或 Kubernetes。

6. 实现交接、工程规则和 ADR

先评审近期 spec/AC，再由实现任务准备适用测试、实现并运行验证；蓝图只记录测试方案与回收证据。差异先区分实现缺陷、需求变更或规格歧义，禁止自动放宽 AC 迁就失败实现。
根 SPEC 明确当前交付范围；近期任务就绪不代表整个 MVP 就绪。Code Review 同时检查契约符合性、代码质量、安全和副作用。
ENGINEERING.md 是代理无关的工程规则来源：实现纪律、测试门禁、仓库约定、常用命令和完成定义。
CLAUDE.md、AGENTS.md 只保存各代理必须立即看到的简短规则、命令和文档路由；不要复制整套项目事实。Cursor 适配仅在用户需要时生成。
对长期、跨模块、代价较高且存在真实候选的选择创建 docs/adr/NNNN-<slug>.md。普通偏好和可轻易撤销的局部选择留在对应文档的决策表。

7. 核查和交付

运行：

python3 <skill-path>/scripts/validate_blueprint.py <project-root>

校验器只读，不自动修复。根据报告处理：缺失文档、孤立 PRD/SPEC、规格场景缺失、失效链接、未登记 TBD、追踪缺口、与当前设计阶段不符的方向/样稿证据/实现规范，以及 spec v2 的 ID/AC/任务依赖/范围覆盖/验收证据和未经复核的 Emoji 使用。基础校验只读，不执行文档内命令、不自动安装协议工具。协议完整性按已选工具单独验证；不可用时标记未验证，结构通过不代表契约或业务验收通过。方向阶段不检查完整视觉参数；实现规范阶段的视觉缺口或未确认样稿阻断 implementation-ready。校验器只检查结构与证据引用，不判断美观程度；Emoji 报告为 warning：删除装饰性使用；确有产品或品牌价值时，在 DESIGN.md 登记例外及可访问性处理。

最后给出：

已创建或更新的文件。
最重要的已确认约束和选型理由。
待决定事项、负责人、截止点及阻断影响。
“可开始设计 / 可开始实现 / 可上线”三个独立结论。
校验命令与结果。

决策纪律

使用 已确认 / 暂定 / 待决定 / 不适用；英文文档对应 confirmed / provisional / pending / not-applicable。
暂定决定必须有采用理由和重新评估条件。
待决定事项使用稳定 ID TBD-<DOMAIN>-NNN，记录 owner、decision-by 和 blocked gate。
技术推荐先列硬约束，再完整展示三套固定参考栈及分析追加项，最后给取舍和推荐。不要用“企业级”“工具型”“简单”标签或流行度代替适配性判断。
发现简化路径时明确提出；发现目标与约束冲突时指出冲突，不通过增加组件掩盖问题。
涉及版本、价格、支持周期、云/商店限制或法规时，只核对官方来源，注明访问日期，并区分事实与建议。
安全或法律高风险内容只能给工程检查清单和需核实事项，不把蓝图当作专业法律结论。

就绪度

可开始设计：核心用户、主要任务、MVP 边界和目标平台已确认；其余缺口不阻断体验设计。
可开始实现：当前交付范围内相关 PRD、功能 SPEC/AC、接口与近期任务契约可验证，关键体验、架构边界、数据/认证方案和测试门禁已确认；有 UI 时已回收视觉确认证据并沉淀实现规范（可复用适用的已认可设计系统）；没有阻断实现的 pending 项。方向草案可开始原型探索，不等于可按定稿批量实现。
可上线：部署责任、环境、密钥、迁移、监控、回滚、备份、恢复目标和适用合规已确认并有验证方式；没有阻断生产的 pending 项。

闸门是结论，不是强迫用户补齐一切的借口。可以交付诚实的草案，但必须说明它还不能支持哪一步。

project-blueprint