From 8a779ea7893b35c6f357172f7b0bc65c52f4fb7c Mon Sep 17 00:00:00 2001
From: liuzhengdong <735083049@qq.com>
Date: Thu, 30 Apr 2026 16:45:27 +0800
Subject: [PATCH] feat: add guidelines for minimum demo creation and spike
 documentation in cs-brainstorm and cs-note skills

---
 cs-brainstorm/SKILL.md                     | 20 ++++++++++++++++++++
 cs-note/SKILL.md                           | 11 ++++++-----
 cs-onboard/reference/shared-conventions.md |  3 +++
 3 files changed, 29 insertions(+), 5 deletions(-)

diff --git a/cs-brainstorm/SKILL.md b/cs-brainstorm/SKILL.md
index 76b4eb1..daf3c93 100644
--- a/cs-brainstorm/SKILL.md
+++ b/cs-brainstorm/SKILL.md
@@ -124,6 +124,26 @@ brainstorm 是"讨论层"统一入口。用户开口时 AI 不知道终点应落
 2. **发散**——确认问题后再谈方案。提 2-3 个具体候选方向（用户带的方案算其中一个），每个 1-2 句描述 / 价值 / 代价。**至少有一个反直觉候选**（反转 / 去掉常见约束 / 跨领域类比）。所有候选呈现完再给推荐——先锚定再补别的会污染用户判断
 3. **收敛**——选定方向后轻轻勾勒：核心行为？明显不做？最大未知？给 design 热身不是替 design 决定
 
+### 什么时候停下来做最小 demo
+
+讨论中冒出"这个方向能不能走得通要看 X 实际是不是 Y"——不要靠脑补辩论，**停下来花 5-30 分钟搭个最小 demo 验一下**比再聊三轮更省时。
+
+**默认不做**——大多数 brainstorm 是在比较权衡，demo 帮不上忙。同时满足下面三条才主动提议：
+
+1. **是事实问题不是偏好问题**——某 API 实际行为 / 库是否真支持 / 性能特征是否成立，不是"哪种风格更好"
+2. **结果会改变方向**——验出来不管成败，讨论都能收敛；如果两种结果对方案影响都不大就别做
+3. **成本可控**——你判断 5-30 分钟内能搭出能跑的东西。超过这个量就不是 spike 了，该走 `cs-feat-ff` 直接做或拆成正式 feature
+
+提议格式：**"这块靠想不准，我做个最小 demo 验一下 {要验的事}，5-10 分钟，OK 吗？"** 用户秒过 / 拒绝即可，不用展开讨论方案。
+
+**spike 落地约定**（保持随意）：
+
+- 实验代码扔 `codestable/brainstorm/{slug}/` 下，文件随便起名（`spike.py` / `try-{topic}.ts`）；slug 沿用 brainstorm 的 slug，没建 feature 目录就用临时关键词
+- 验完不强制清理——留着以后看也行，影响不大；用户嫌乱说一声再删
+- **结果必须回写 brainstorm note**——成败都要在"已敲定的设计点"那节记一条："{结论} —— 已用 spike `codestable/brainstorm/{slug}/{file}` 验证"，避免 design 阶段再起疑重做
+
+case 1 / case 3 也能借这个动作（不强求落 brainstorm note），逻辑一样：事实存疑 + 改变方向 + 成本可控。
+
 ### 随时升降级
 
 - 发现是大需求（子模块越聊越多有依赖）→ "这规模超出单 feature 建议切 roadmap"，按 case 3 移交
diff --git a/cs-note/SKILL.md b/cs-note/SKILL.md
index 98f2b51..4943f40 100644
--- a/cs-note/SKILL.md
+++ b/cs-note/SKILL.md
@@ -45,12 +45,13 @@ cs-learn / cs-trick / cs-decide 产出独立 markdown 文件，**通过检索**
 
 ## 目标文件
 
-按项目实际有的来，**不主动新建**：
+按项目实际有的来，**不主动新建、不替用户拍偏好**：
 
-- 项目根有 `AGENTS.md` → 写这里
-- 没有但有 `CLAUDE.md` → 写这里
-- 两个都有 → 默认写 `AGENTS.md`（更通用），除非用户指定
-- 两个都没 → 提示用户："项目还没有 AGENTS.md / CLAUDE.md，要不要我先建一个 AGENTS.md？" 用户同意再建
+- 项目根只有一个（`AGENTS.md` 或 `CLAUDE.md`）→ 写已有的那个，不问
+- 两个都有 → **问用户** "本次写到 `AGENTS.md` 还是 `CLAUDE.md`？" 等用户回复再动
+- 两个都没 → **问用户** "项目还没有常驻上下文文件，要建哪个？`AGENTS.md` / `CLAUDE.md` / 其他文件名（如 `.cursorrules`）？" 用户答复后再建
+
+不主动定默认——AI 工具自己注入的提示词会告诉模型该读哪个，工具偏好该由用户和工具决定，cs-note 不替用户预设。
 
 **不写到 codestable/ 下**——本技能的全部价值就是利用"自动加载"，写到 codestable/ 里就失去意义。
 
diff --git a/cs-onboard/reference/shared-conventions.md b/cs-onboard/reference/shared-conventions.md
index 4efde1d..02b5d16 100644
--- a/cs-onboard/reference/shared-conventions.md
+++ b/cs-onboard/reference/shared-conventions.md
@@ -43,6 +43,9 @@ codestable/
 ├── compound/              沉淀类文档统一目录
 │   └── YYYY-MM-DD-{doc_type}-{slug}.md
 │                          doc_type ∈ {learning, trick, decision, explore}
+├── brainstorm/            brainstorm 阶段 spike 实验代码区（cs-brainstorm 临时产出）
+│   └── {slug}/            一次 spike 一个子目录，文件名随意
+│                          验完不强制清理，结论回写到对应 brainstorm note
 ├── tools/                 跨工作流共享脚本（onboarding 从技能包释放）
 └── reference/             共享参考文档（onboarding 从技能包释放）
 ```