nanospec
NanoSpec 的核心是 AI 工作中间文档的目录规范与 align 纠偏机制;可独立配合其他 plan/research/execute 类 skill 使用,也可在需要时路由为完整的 spec-driven workflow。
SKILL.mdpackages/nanospec/skills/nanospec/SKILL.md
GitHubNanoSpec
目标
先提供一套稳定的 AI 工作中间文档目录规范,让 plan、research、execute 等其他 skill 也能在同一任务容器里协作;当用户需要时,再由这个 skill 路由并补齐完整的 NanoSpec spec-driven workflow。
这个 skill 的默认定位不是“必须从 init 开始跑完整流程”,而是:
- 约束中间文档落盘位置、命名和读取顺序。
- 在出现偏差、变更、缺失、歧义时,用 align 作为统一纠偏入口。
- 在用户明确要求或上下文显示需要时,再承接 init / clarify / spec / plan / execute / accept / summary / onboard / run。
何时使用
- 你想给当前任务建立稳定的中间文档目录,而不是把计划和决策散落在对话里
- 任务已经进入 plan / research / execute,但缺少统一的任务容器和回写规则
- 任务里出现范围变化、需求偏差或临时决策,需要用
alignment.md做统一纠偏 - 你想按
/init、/plan、/execute、/align这类阶段入口推进,而不是每次重新描述流程 - 你明确希望由 NanoSpec 续跑一套完整的 spec-driven workflow
不适用:
- 只是一次性极小改动,不需要任务容器或中间文档
- 用户只要最终答案,不希望保留任何项目内过程产物
产物
每次使用本 skill,默认产出以下最小集合:
- 任务容器
nanospec/<YYYYMMDD-task-name>/- 需要时可同步维护
.nanospec/.current
- 对齐记录
- 出现偏差、变更、缺失、歧义时写入
alignment.md
- 出现偏差、变更、缺失、歧义时写入
- 共享工作面
outputs/1-spec.mdoutputs/2-plan.mdoutputs/3-tasks.md
- 辅助资料
assets/下的研究、截图、日志、草图和补充文档
默认要求:
- 没有任务容器时,先创建容器,再进入具体阶段
- 发生口径变化时,不能只改对话,必须回写
alignment.md和受影响产物 outputs/3-tasks.md是跨 skill 的共享执行面,不是 NanoSpec 私有日志
任务目录结构
project-root/
├── .nanospec/
│ └── .current # 当前任务名,可选
└── nanospec/
└── <YYYYMMDD-task-name>/
├── brief.md # 简述需求,和 prd.md 二选一或并存
├── prd.md # 更正式的需求文档,可选
├── alignment.md # 对齐记录,可按需创建
├── assets/
│ ├── README.md # 可选,记录放置建议
│ └── ... # 资料、截图、草图、补充文档
└── outputs/
├── 1-spec.md
├── 2-plan.md
├── 3-tasks.md
├── acceptance.md # 可选,验收阶段生成
└── summary.md # 可选,总结阶段生成
- 仓库里没有
nanospecCLI 时,也按上面的结构直接创建和维护文件。 - 新建任务目录名必须使用
YYYYMMDD-任务主题格式,例如20260315-skills跨工具安装指南。 .nanospec/.current只是任务指针,不是 skill 生效的前置条件。- 用户完全可以只采用这套目录规范,而不使用 NanoSpec 的其他阶段能力。
- 简单任务可以把截图、日志、接口样例、参考链接直接平铺在
assets/下。 - 只有材料明显变多、类型混杂时,才建议拆成
research/、bugs/、api/、data/、ui/、references/等子目录。 alignment.md不需要预创建;只有真正发生偏差、变更、缺失或歧义时,再由/align或其他阶段补写。
工作流
- 优先从用户显式输入解析任务目录,其次读取
.nanospec/.current;仍无法定位时,按YYYYMMDD-任务主题格式在nanospec/下手动创建目录。 - 按顺序读取
alignment.md、brief.md/prd.md、assets/*与工作区现状。 - 只执行本次请求真正需要的阶段;如果当前任务来自其他 skill 的 plan、research、execute 指令,也继续沿用这套目录规范。
- 只要出现需求变化、实现偏差或临时决策,先执行 align:更新
alignment.md,同步所有受影响产物,再继续其他阶段或其他 skill。 - align 产生的后续动作必须回写到
outputs/3-tasks.md,不能只停留在对话或alignment.md。 - 每完成一个可执行事项,立即更新
outputs/3-tasks.md。 - 如果用户要求
/run,或明确希望由 NanoSpec 接管完整流程,再按缺失阶段自动续跑完整 workflow。
协作边界
- 这个 skill 可以只提供“目录规范 + align”,把 spec、plan、research、execute 交给别的 skill 完成。
- 当其他 skill 采用“先 plan 后 xxx”模式时,只要装载了本 skill,就应按本目录规范读写中间文档。
outputs/2-plan.md和outputs/3-tasks.md不是 NanoSpec 私有产物;它们也是跨 skill 协作时的共享工作面。- align 是核心能力,不依赖完整 workflow 才能使用。
- 完整的 spec-driven workflow 是可选路由,不是使用本 skill 的前提条件。
Align 机制
align 不是一个孤立阶段,而是贯穿整个任务生命周期的变更传播机制。参考领域 _AGENTS.md 中的通用规则,它的核心循环是:
- 发现问题。
- 记录到
alignment.md。 - 同步受影响产物。
- 回写新的执行动作到
outputs/3-tasks.md。
触发 align 的时机不限于 /align:
- 在 spec 阶段发现需求冲突、歧义、缺失时,要立即 align。
- 在 plan 阶段发现口径不一致、方案风险时,要立即 align。
- 在 execute 阶段发现实现偏差、阻塞问题时,要立即 align。
- 在 accept 或 summary 阶段发现遗漏决策点时,也要立即 align。
align 记录应使用统一标签:[偏差] [变更] [缺失] [歧义] [冲突]。需要用户确认时,再追加 `⏳ 待确认`。
只要口径发生变化,就必须同步更新受影响的 outputs/1-spec.md、outputs/2-plan.md、outputs/3-tasks.md,以及存在时的 acceptance.md。不能只改 alignment.md,也不能只留在对话里。
路由方式
使用这个 skill 时,可以直接用 /xxx 把请求路由到对应阶段,而不必先声明“进入某个内部模式”。
/init:初始化任务目录或建立当前任务上下文。/clarify:补需求澄清。/spec或/1-spec:产出规格说明。/plan或/2-plan:产出方案与任务拆解。/execute或/3-execute:按任务清单推进实现。/align:执行对齐纠偏,并传播变更。/accept:生成或更新验收产物。/summary:沉淀总结。/onboard:进入带教学解释的引导模式。/run:让 NanoSpec 按缺失阶段续跑完整 workflow。
如果外部工具或团队约定使用的是带前缀命令,例如 /spec.align、/spec.2-plan,也可以继续使用;本 skill 的要求是“按当前意图路由到对应 reference 和目录规范”,而不是强绑定某一种命名形式。
辅助脚本
skill 目录内自带 scripts/create_task_skeleton.py,用于快速创建符合约定的任务骨架。优先使用 Python 标准库脚本,是为了比 shell 更容易跨不同 agent 环境复用:
python3 scripts/create_task_skeleton.py "支付回调重试"
python3 scripts/create_task_skeleton.py "20260315-支付回调重试" --set-current
脚本会创建:
nanospec/<YYYYMMDD-task-name>/brief.mdnanospec/<YYYYMMDD-task-name>/assets/README.mdnanospec/<YYYYMMDD-task-name>/outputs/1-spec.mdnanospec/<YYYYMMDD-task-name>/outputs/2-plan.mdnanospec/<YYYYMMDD-task-name>/outputs/3-tasks.md
如果传入的是不带日期前缀的主题名,脚本会自动补上当天的 YYYYMMDD- 前缀;传入 --set-current 时,会同步写入 .nanospec/.current。
渐进加载
只加载当前意图需要的参考文件:
- 创建或初始化任务:
references/init.md - 快速续跑全流程:
references/run.md - 需求澄清:
references/clarify.md - 规格产出:
references/spec.md - 对齐更新:
references/align.md - 规划与任务拆解:
references/plan.md - 任务执行:
references/execute.md - 验收校验:
references/accept.md - 交付总结:
references/summary.md - 新人上手:
references/onboard.md
全局规则
- align 不是可选补记;出现偏差或变更时,继续 spec / plan / execute 之前必须先完成 align 回写。
- 当其他 plan / research / execute skill 已经装载本 skill 时,也要沿用同样的目录规范与 align 约束。
- 使用
/xxx路由阶段时,也必须遵守同一套目录规范、align 机制与回写要求。 - 需求变化统一记录到
alignment.md,并使用标签:[偏差] [变更] [缺失] [歧义] [冲突]。 - 只有真正阻塞推进的确认项,才使用
`⏳ 待确认`。 - 不要把后续行动只留在对话里,必须回写到
outputs/3-tasks.md。 outputs/3-tasks.md只跟踪交付动作与状态,不记录 commit hash、提交信息或“补任务日志”这类 git 元信息。- 除非用户明确要求调用 CLI,否则不要把
nanospec init、nanospec new、nanospec status、nanospec switch当成前置步骤。 - 保持现有文件语言和风格,除非用户明确要求调整。