About

Imported from ramiro-qq/my-skills (skills/requirements-to-tech/SKILL.md). Install upstream with npx skills add ramiro-qq/my-skills --skill requirements-to-tech. Copyright stays with the author (MIT).

Requirements To Tech

Name: requirements-to-tech
Author: ramiro-qq

目标

把“新增需求”转换成“实现前对齐文档”。

这份技能的作用不是直接开始编码，而是先基于项目现状、现有约束和真实代码，把需求收敛成一份可执行、可验证、可回溯的技术方案，作为后续开发人员与模型共同遵循的实现目标，避免代码实现逐步偏离原始需求。

什么时候使用

用户要求输出技术方案、技术设计、技术实现方案、架构方案、开发方案。
用户提供了 PRD、需求文档、功能说明、设计稿，希望先对齐方案再开发。
用户想新增页面、功能、模块，或进行结构调整、重构、项目初始化。
需求跨多个模块、影响范围较大，直接编码容易出现理解漂移。

什么时候不必使用

只是一个非常小的局部修复，且目标、边界、实现方式都已经非常明确。
用户明确要求直接实现，且任务足够简单，不需要单独形成技术方案文档。
当前任务只是解释一段代码或回答一个局部技术问题。

核心原则

必须先完成技术方案设计，再开始编码。
技术方案必须建立在“当前项目事实”上，不能套用脱离上下文的通用模板。
先盘点现状，再设计增量；必须区分“当前事实”“目标设计”“开放问题”。
技术方案是后续实现的目标约束，不是可有可无的建议稿。
简单需求可以简化方案，但不能跳过方案步骤。
复杂需求必须按 references/tech-plan-template.md 输出完整方案。
设计过程中如果发现关键歧义、规则缺失、边界不清、用户意图可能存在多解，必须及时向用户发问确认，不必等整份方案写完再集中提问。
如果后续实现与方案冲突，必须先说明偏差并更新方案，不能静默偏离。
对应场景的 reference 不是“可选参考”，而是“必需落实的输入合同”；读取后必须把关键要求显式回填到方案文档。
若必填项缺失、reference 未落实、命名不合规或关键歧义未处理，不得宣称“技术方案已完成”。

执行闸门

在输出最终方案前，必须同时满足以下条件，否则只能输出“未完成方案 + 缺失项/待确认项”，不能输出“已完成技术方案”：

已重新读取本次需求相关文件与项目上下文
已识别当前任务属于“新增 / 改造 / 初始化 / 拆分 / 收敛”中的哪一种
若是创建新项目，已读取对应 reference
已将对应 reference 的关键要求回填到方案正文，而不是只在脑中参考
已完成阻断式自检
最终摘要已明确说明“当前仅完成技术方案，尚未开始编码”

读取范围

在生成技术方案前，必须读取与本次需求直接相关的项目信息，包括但不限于：

用户提供的需求描述、PRD、设计稿、说明文档。
项目约定文件，例如 AGENTS.md、README、项目内规则文档。
当前项目的构建配置、依赖配置、目录结构、核心代码入口。
与需求直接相关的页面、组件、路由、接口、hooks、工具函数、架构文档。

这些内容必须在每次生成技术方案之前重新读取，不要把某个项目当前的技术栈、规则、文件路径、模块结构硬编码在本技能正文里。

明确忽略范围

扫描项目代码时，不要把以下内容当成主要分析对象，除非用户明确要求：

node_modules
dist
build
.next
.turbo
.cache
coverage
临时文件、缓存文件、日志文件
大型产物目录、自动生成目录、无关截图或导出文件

目标是聚焦“当前真实源码、配置、约定和需求相关文档”，避免被构建产物和依赖噪音干扰。

工作流程

1. 明确需求来源和输出目标

先确认需求来自哪里：用户口述、PRD、需求文档、设计稿、缺陷描述或任务说明。
用简洁语言总结本次要解决的问题、目标用户、预期结果和影响范围。
如果用户没有指定文档落盘位置，必须输出到 .tmp/docs/architectures/YYYY-MM-DD-[需求简称].md。
这里的 [需求简称] 必须使用本次需求的中文简称，直接取自需求语义本身，不要擅自改成英文、拼音、泛化主题词或自创标题。
[需求简称] 应尽量简短且可辨识，优先控制在 4 到 12 个中文字符内；如果需求本身较长，应提炼成能准确指代本次需求的中文短语。
除非用户明确指定了其他路径或文件名，否则不得偏离上述命名格式。
如果已经落盘但文件名不符合该规则，必须先重命名为合规文件名，再继续后续输出。

2. 读取项目现状

读取项目规则、代码结构、依赖配置和相关模块。
识别当前已有能力、当前缺口、可直接复用的模块和潜在冲突点。
只读取与本次需求相关的文件，不做无边界全仓扫描。

3. 做增量分析

明确本次是在现有基础上新增、替换、收敛、拆分还是初始化。
列出 in scope / out of scope。
如果需求本身存在模糊点，把它们列为假设或开放问题，不要擅自补完业务规则。
对关键歧义要边分析边提问，及时向用户确认，而不是把所有问题拖到最后一次性询问。
对“阻断问题”和“非阻断问题”分开处理：
- 阻断问题：不确认就无法形成可信方案，必须先问用户
- 非阻断问题：可先写入假设与开放问题，再继续产出方案

4. 设计技术方案

从真实代码结构出发，设计模块、目录、页面、组件、路由、接口、状态、数据流和错误处理。
需要说明复用点、改造点、新增点和风险点。
必须具备全局视野，不只解决当前页面或局部功能；要从公共组件抽取、全局主题变量、组件复用、接口参数设计、功能模块拆分、架构扩展性、可配置性、性能和系统枚举等方面统一设计。
涉及 UI 时，要写清桌面端 / 移动端、关键状态、交互反馈和可访问性。
涉及接口时，要写清请求入口、触发时机、返回处理、失败路径和登录失效行为。
必须考虑异常状态处理，包括但不限于：无数据、加载中、接口报错、代码报错、权限受限、局部失败、重试与兜底。
方案内容必须包含“重难点功能详细设计”，把复杂的、不易理解的、有争议的、用户重点关注的功能设计清楚，不能只停留在模块级罗列。

5. 需要建新项目时调用对应参考文档

如果需求涉及“创建项目”而不是“改已有项目”，必须读取对应 reference：

前端项目：references/create-frontend.md
Python 项目：references/create-python.md
React Native 项目：references/create-react-native.md
Java 项目：references/create-spring.md

这些 reference 用来补充项目初始化、技术选型、目录规划、依赖安装和后续技能安装要求。

读取后必须执行以下动作，缺一不可：

在方案文档中新增 Reference 约束落实 小节
明确列出“已读取的 reference 文件路径”
逐条说明该 reference 的关键要求已落到方案的哪一节
如果某一条要求暂未落实，必须写明“未落实项 + 原因 + 后续处理”

6. 输出方案

简单需求：输出简化版技术方案，保留目标、现状、改造点、风险、验证方式。
复杂需求：按 references/tech-plan-template.md 输出完整技术方案。
输出结果必须能直接作为后续实现目标，而不是泛泛描述。
如果套用了完整版模板，不能只保留章节名；必须把本场景特有的强制项补齐。

7. 结束于方案，不进入编码

技术方案完成后，应明确说明当前阶段只完成了方案设计。
未经用户明确要求，不要继续写实现代码。

技术方案必须包含什么

无论是简版还是完整版，至少要覆盖：

需求来源与目标
当前现状与限制
本次增量范围
推荐实现路径
目录 / 模块 / 组件 / API / 状态流设计
全局设计考虑
重难点功能详细设计
异常状态处理设计
风险与开放问题
验证建议

如果需求较复杂，还应补充：

备选方案与取舍理由
分阶段实施计划
回滚或降级策略
Mermaid 图辅助说明

场景化强制输出合同

以下合同用于把“读了 reference”升级为“文档必须出现的显式结果”。如果命中某个场景，则对应条目全部为必填项。

前端新项目初始化

当需求属于“初始化前端项目 / 从零创建前端项目 / 在空仓或已有仓库内新增前端项目”时，必须读取 references/create-frontend.md，并在方案中显式包含以下内容；缺一项则视为方案未完成：

项目类型判定：SPA / SSR
判定理由：为什么采用该类型，而不是另一种类型
已有仓库约束确认
已有部署约束确认；若未知，必须明确写“当前未知”
已有 UI 组件约束确认；若无现成体系，必须明确写“本次采用的默认体系”
推荐技术栈和选型理由
初始化命令草案
目录结构草案
核心依赖清单：
- 运行时依赖
- 开发时依赖
路由模式
请求层封装方式
异步状态管理方式
UI 组件体系与主题方案
代码规范与验证命令
后续需要安装的 skills
根目录 AGENTS.md 初始化方案
Reference 约束落实 小节

若项目类型为 SPA，方案中至少还必须写清以下具体约束：

为什么采用 SPA
默认基础栈为 pnpm + Vite + Tailwind CSS + shadcn/ui + axios + ahooks
能复用 ahooks 现成 hooks 的场景为什么必须优先复用，而不是自定义重复实现
API 管理目录为什么必须固定为 src/api
axios 在请求层中的职责边界
ahooks 在异步状态管理中的职责边界
为什么接口请求应统一使用 ahooks/useRequest + axios 统一实例
为什么不应再额外封装自定义通用 useRequest
当前目录非空时，为什么前端项目根目录应落在 frontend/
为什么初始化阶段必须创建仓库根级 AGENTS.md
AGENTS.md 中哪些内容属于固定规则，哪些属于动态规则
如果方案建议安装 skills，安装命令为什么必须显式写出，而不是只列 skill 名称

若方案中未完整体现 skills.sh 安装要求，则不得声称“已按前端初始化 reference 完成方案设计”。

若项目类型为 SPA，方案中还必须满足以下实现落地约束，缺一项则视为未完成：

API 管理目录写为 src/api，不得改写成其他路径
页面或业务模块调用接口时，默认模式写为“src/api 中 API 方法 + ahooks/useRequest”
不得设计自定义通用 useRequest 替代层
若需要新增 hooks，必须先说明为什么 ahooks 现有 hooks 无法满足
必须在初始化方案中明确：项目初始化时应在仓库根目录创建 AGENTS.md
必须明确 AGENTS.md 的最小章节集合，至少覆盖：
- 仓库基本情况与技术栈
- 常用命令
- 工程结构
- 路由约定
- 项目约定、技术栈约定、UI 约定、注释、文档与说明约定
必须明确 AGENTS.md 中的固定规则与动态规则划分方式
若方案建议安装 skills，必须给出真实可执行命令，默认格式为：
- npx skills add https://github.com/<owner>/<repo> --skill <name> -a codex -y
方案中不得保留 <owner>、<repo>、<name> 占位符，必须替换为真实值
若安装失败，必须明确写出“可按同一命令最多重试三次”

Python 新项目初始化

当需求属于“初始化 Python 项目 / 从零创建 Python 项目”时，必须读取 references/create-python.md，并把该 reference 中的初始化、依赖、目录、验证和后续技能安装要求逐条回填到方案文档。

React Native 新项目初始化

当需求属于“初始化 React Native 项目”时，必须读取 references/create-react-native.md，并把其关键要求逐条回填到方案文档。

Java 新项目初始化

当需求属于“初始化 Java / Spring 项目”时，必须读取 references/create-spring.md，并把其关键要求逐条回填到方案文档。

输出要求

最终输出应包含两部分：

1. 方案文档结果

文档路径
或直接给出完整 Markdown 正文
如果选择落盘文档，且用户未明确指定其他命名，则返回的文档路径必须是 .tmp/docs/architectures/YYYY-MM-DD-[需求简称].md 这一格式的实际文件路径，而不是语义接近但不合规的变体。

2. 简洁摘要

需求来源
本次读取了哪些项目上下文
推荐方案一句话结论
主要影响范围
风险与待确认项
明确说明“当前仅完成技术方案，尚未开始编码”

3. 固定回执

无论是简版还是完整版，最终回复中都必须附带以下回执信息：

场景判定结果
本次读取的文件清单
若读取了 reference：Reference 约束落实摘要
若存在未落实项：明确列出未落实项，不得省略

固定输出格式

最终输出建议按以下顺序组织；如果内容缺失，必须显式写“当前未知”或“待确认”，不能静默跳过：

方案文档结果
场景判定结果
本次读取的项目上下文
Reference 约束落实摘要
推荐方案一句话结论
主要影响范围
风险与待确认项
当前仅完成技术方案，尚未开始编码

禁止事项

不要跳过方案阶段直接写代码。
不要只复述需求，不结合项目代码现状。
不要把项目当前的技术栈、路径规则、目录结构固化在技能正文里。
不要扫描无关目录制造噪音。
不要在没有证据的情况下臆断接口、目录或模块职责。
不要遗漏用户补充的关键细节；无法确定时应写入开放问题。
不要只做局部设计而忽略系统级复用、扩展性、可配置性和异常处理。
不要把复杂功能只用一句话带过，必须展开重难点详细设计。
不要在用户未指定文件名时，自行把方案文档命名成英文标题、技术描述、topic slug、tech-plan、design、proposal 等变体文件名。
不要把“已读取 reference”当成“已满足 reference”；未回填到方案正文视为未落实。
不要把场景化必填项折叠成一句泛化描述，必须逐项明确写出。
不要在自检未通过时输出类似“方案已完成”“可直接进入实现”的结论。

阻断式自检

输出最终结果前，必须逐项检查。只要有一项答案为“否”，就不能宣称方案完成，必须继续补齐或向用户确认：

是否先完成了技术方案，再考虑编码？
是否读取了本次需求相关的项目规则和代码，而不是套模板？
是否显式忽略了 node_modules、dist、缓存和临时产物？
是否区分了“当前事实”“目标设计”“开放问题”？
过程中如果出现关键歧义，是否已经及时向用户确认，而不是拖到最后？
是否根据简单/复杂需求选择了合适的输出深度？
是否包含全局设计、重难点功能详细设计和异常状态处理？
如果涉及新项目创建，是否读取了对应的 reference 文档？
如果读取了 reference，是否在方案正文中增加了 Reference 约束落实 小节？
是否已经覆盖命中场景的全部“场景化强制输出合同”条目？
输出是否足以作为后续实现目标，而不是仅供参考的说明？
如果输出了落盘文档：文件名是否严格符合 .tmp/docs/architectures/YYYY-MM-DD-[需求简称].md，且 [需求简称] 使用的是本次需求的中文简称而不是英文自拟标题？
最终回复是否包含固定回执，并明确说明“当前仅完成技术方案，尚未开始编码”？

失败处理

如果无法满足本 skill 的强制要求，必须显式说明失败原因，而不是隐式降级：

如果缺少关键信息，先提最少量的澄清问题
如果缺少非阻断信息，写入假设与开放问题
如果 reference 已读取但仍无法落实，输出“未落实项 + 原因 + 建议补救动作”
如果阻断式自检未通过，最终只能输出“当前为未完成方案”

Agent Notes

Generic behavior: 先读需求、再读项目上下文、最后输出技术方案，这个工作流对支持文件检索和 Markdown 输出的 Agent 都成立。
Codex-specific note: 如果运行环境提供更强的 workspace 搜索、计划或终端工具，可以用来加速上下文收集，但不要把这些工具写成技能的前置要求。
Fallback behavior: 如果目标 Agent 不支持同样的工具集，就退回到基础文件搜索、命令行检查和手工整理方案文档，保持“先方案、后编码”的约束不变。

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/ramiro-qq-my-skills-requirements-to-tech/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

ramiro-qq-my-skills-requirements-to-tech.ocm.jsonjson

{
  "ocm": "1",
  "id": "ramiro-qq-my-skills-requirements-to-tech",
  "kind": "skill",
  "name": "requirements-to-tech",
  "description": "当需要把新增需求、PRD、功能简报或用户描述，结合项目当前代码、规则与约束，先沉淀为后续实现必须对齐的技术方案时使用。",
  "publisher": "ramiro-qq",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "requirements",
      "prd",
      "tech-plan",
      "architecture",
      "design",
      "planning",
      "implementation-alignment",
      "github"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "当需要把新增需求、PRD、功能简报或用户描述，结合项目当前代码、规则与约束，先沉淀为后续实现必须对齐的技术方案时使用。"
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "github",
      "repository": "https://github.com/ramiro-qq/my-skills",
      "path": "skills/requirements-to-tech/SKILL.md",
      "ref": "34ffc45329d170886d475b5420430e612ebfc3e1",
      "url": "https://github.com/ramiro-qq/my-skills/blob/34ffc45329d170886d475b5420430e612ebfc3e1/skills/requirements-to-tech/SKILL.md",
      "key": "ramiro-qq/my-skills/skills/requirements-to-tech/SKILL.md"
    },
    "license": "MIT"
  },
  "instructions": "# Requirements To Tech\n\n## 目标\n\n把“新增需求”转换成“实现前对齐文档”。\n\n这份技能的作用不是直接开始编码，而是先基于项目现状、现有约束和真实代码，把需求收敛成一份可执行、可验证、可回溯的技术方案，作为后续开发人员与模型共同遵循的实现目标，避免代码实现逐步偏离原始需求。\n\n## 什么时候使用\n\n- 用户要求输出技术方案、技术设计、技术实现方案、架构方案、开发方案。\n- 用户提供了 PRD、需求文档、功能说明、设计稿，希望先对齐方案再开发。\n- 用户想新增页面、功能、模块，或进行结构调整、重构、项目初始化。\n- 需求跨多个模块、影响范围较大，直接编码容易出现理解漂移。\n\n## 什么时候不必使用\n\n- 只是一个非常小的局部修复，且目标、边界、实现方式都已经非常明确。\n- 用户明确要求直接实现，且任务足够简单，不需要单独形成技术方案文档。\n- 当前任务只是解释一段代码或回答一个局部技术问题。\n\n## 核心原则\n\n- 必须先完成技术方案设计，再开始编码。\n- 技术方案必须建立在“当前项目事实”上，不能套用脱离上下文的通用模板。\n- 先盘点现状，再设计增量；必须区分“当前事实”“目标设计”“开放问题”。\n- 技术方案是后续实现的目标约束，不是可有可无的建议稿。\n- 简单需求可以简化方案，但不能跳过方案步骤。\n- 复杂需求必须按 `references/tech-",
  "cost": {
    "context_tokens": 1880
  }
}

Fetch it by URL: GET /api/v1/registry/ramiro-qq-my-skills-requirements-to-tech/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.