project-setup

name	project-setup
description	项目配置向导。首次使用或配置未完成时触发。探测项目现状，通过最少的对话完成配置。后续标准在开发中自然积累。

项目配置向导

目标：让用户尽快开始描述需求。配置越少越好，AI 能推断的不问，必须用户决定的才问。 文档是给 AI 跨会话使用的，不是给用户读的。

触发时机

• SessionStart hook 检测到配置未完成时自动提示
• 用户手动调用 /project-setup

当前配置状态

!grep -q "\[项目名称\]" CLAUDE.md 2>/dev/null && echo "CLAUDE.md: ❌ 未配置" || echo "CLAUDE.md: ✅ 已配置"

!grep -q "\[用 2-3 句话" docs/RUBRIC.md 2>/dev/null && echo "RUBRIC.md: ❌ 未配置" || echo "RUBRIC.md: ✅ 已配置"

!grep -q "\[待定义\]" docs/ARCHITECTURE.md 2>/dev/null && echo "ARCHITECTURE.md: ❌ 未配置" || echo "ARCHITECTURE.md: ✅ 已配置"

---

核心原则

1. 先对齐规则再开发 — 配置是必要的，AI 负责提效，用户负责决策
2. AI 做分析和推荐，用户做选择和决定 — AI 提出方案和理由，用户确认、修改或提出自己的想法
3. 所有配置项都要用户过目确认 — 即使 AI 能从代码推断，推断结果也要呈现给用户确认，不能静默写入
4. 标准在对齐后启动，在开发中持续积累 — 初始配置建立基线，后续用户反馈持续补充
5. 文档是给 AI 用的 — 用户不需要维护，但配置内容由用户决定

执行流程

阶段一：自动探测

在问任何问题之前，先从项目中采集能采集的一切：

1. 包管理文件：package.json / pyproject.toml / Cargo.toml / go.mod / pom.xml → 推断：项目名称、描述、技术栈、依赖
2. 配置文件：tsconfig.json / .eslintrc* / prettier.config* / Dockerfile → 推断：语言版本、代码规范、部署方式
3. 目录结构：ls 项目根目录和 src/ 目录 → 推断：架构分层
4. 已有代码（如果有）：扫描 import/require 关系 → 推断：模块依赖方向、实际的分层规则
5. 已有文档：README.md、.env.example → 推断：项目描述、涉及的外部服务

如果项目是空的（刚 init 或刚创建），跳过探测，进入阶段二。

阶段二：推荐方案 + 用户决定

AI 基于探测结果形成推荐方案，逐项呈现给用户确认。每一项都是"AI 推荐 + 理由 + 用户是否有别的想法"。

已有代码的项目

逐项呈现推断和推荐：

项目信息 "从 package.json 看，项目叫 xxx，描述是 yyy。对吗？"

技术栈 "我检测到的技术栈是：前端 Next.js + TypeScript，后端 Next.js API Routes，数据库 Prisma + [PostgreSQL?]，测试未检测到。

1. 数据库确认是 PostgreSQL 吗？
2. 测试框架你打算用什么？我推荐 Vitest（因为和 Next.js 生态搭配好），你觉得呢？"

架构 "从目录结构和 import 关系，我推断的架构是：

app/ → components/ → lib/services/ → lib/repositories/ → Prisma

依赖规则：组件不直接调数据库，业务逻辑在 services 层。 这是你想要的结构吗？还是你有别的分层想法？"

类型共享方式（仅适用于有前后端交互的项目） "你的前后端如何共享类型定义？常见方式有：

1. monorepo 共享包（直接 import）
2. OpenAPI schema + 代码生成
3. tRPC（TypeScript 全栈）
4. GraphQL schema
5. 手动维护共享类型文件

你已经有方案了吗？还是想听我的建议？"

确认后写入 ARCHITECTURE.md 的"前后端类型契约"部分的 [待定义]。

代码标准 "关于代码标准，你有没有：

• 特别想要的技术实践或代码风格？
• 特别讨厌的写法或踩过的坑？ 这些会作为项目的评分标准，指导后续开发方向。没有的话可以先跳过，开发中随时补充。"

每项等用户回答后再问下一项。用户的回答可能修正推断、补充信息、或提出完全不同的方案——都要尊重用户的选择。

空项目

项目目标 "你想做什么？"

根据回答，AI 给出完整的技术方案推荐：

技术栈推荐 "基于你的需求，我推荐以下技术栈：

• 前端：[推荐] — [理由]
• 后端：[推荐] — [理由]
• 数据库：[推荐] — [理由]
• 测试：[推荐] — [理由]

如果你有其他偏好（比如已经熟悉某个框架），告诉我，我会基于你的选择调整架构。"

架构推荐 "基于 [技术栈] 和你的需求规模，我推荐的架构是：

• [分层方案] — [理由]
• [关键依赖规则] — [理由]

你觉得这个方案怎么样？还是有别的想法？"

有多个合理选择时（如 Next.js vs Remix，monolith vs microservice），列出各选项的优劣对比，让用户选。AI 可以表达推荐倾向，但不替用户决定。

代码标准 "你对代码风格有什么偏好吗？比如：

• 函数式还是面向对象？
• 有没有特别讨厌的写法？ 没有的话先跳过，开发过程中随时告诉我。"

阶段三：确认总览

所有项讨论完后，汇总一份总览给用户最终确认：

"总结一下我们确定的方案：

• 项目：[名称] — [描述]
• 技术栈：[前端] / [后端] / [数据库] / [测试]
• 架构：[分层概述]
• 关键规则：[1-2 条最重要的约束]
• 代码标准：[已确认的惩罚/奖励项，或"后续积累"]

确认后我就写入配置，可以开始做第一个功能了。有要改的吗？"

用户确认后进入写入阶段。如果用户要改，当场改对应项，不重跑整个流程。

阶段四：写入配置

用 Edit 工具精确替换占位符，不要重写整个文件。

CLAUDE.md

• 替换 [项目名称] 和 [一句话描述]
• 填入确认的技术栈

ARCHITECTURE.md

• 基于用户确认的架构方案填入分层图、依赖规则、目录约定
• 命名规范根据用户确认的技术栈推断合理默认值（如 React 用 PascalCase 组件名）
• 关键约束根据用户确认的架构决策填入

RUBRIC.md

• 通用基线维度保留模板默认值
• 项目特定标准：写入用户明确说过的偏好/反感
• 如果用户跳过了标准设定，写入："项目特定标准将在开发过程中根据用户反馈逐步积累"
• 权重：如果用户强调了某个维度，相应调高；否则用默认值（功能 20% / 代码 20% / 设计 25% / 架构 25% / 文档 10%）
• 权重也要给用户确认，不要静默使用默认值

settings.json — lint/类型检查 hook

根据确认的技术栈，在 .claude/settings.json 的 PostToolUse hooks 中追加 lint/类型检查命令。示例：

• TypeScript：npx tsc --noEmit 2>&1 | head -20; npx eslint --quiet "$FILEPATH" 2>/dev/null; exit 0
• Python：ruff check "$FILEPATH" 2>/dev/null; exit 0
• Go：go vet ./... 2>&1 | head -20; exit 0
• Rust：cargo check 2>&1 | head -20; exit 0

matcher 设为 Write|Edit|MultiEdit（和 prettier hook 同组）。exit 0（提醒模式）或 exit 2（阻断模式），推荐用 exit 0 避免开发中频繁阻断。

如果用户不确定用什么 lint 工具，根据技术栈推荐最主流的选择。

docs/context/（活上下文链起步 — 只填 L1+L2，克制）

剂量轻：起步只落愿景 + 需求单表两个种子（setup.sh 已铺），L3-L6 随真实开发自然长，不预填空壳。

• docs/context/L1-vision.md：把阶段二/三确认的项目目标（用户原话）写进正文，status 改 active。
• docs/context/L2-INDEX.md：把已确认的首批功能逐行填入单表（编码 L2-F1、L2-F2…），upstream 都填 L1-vision；还没定的功能留一行 待定，不强行凑。
• 用户没有明确功能清单时，L2 表保留一行 [待填]/待定 即可，开发中再补 —— 与 RUBRIC 渐进式积累同基调，不在配置阶段逼用户填满。
• frontmatter 与 upstream 只用半角 [ ] : ,（全角会被 check-context-chain.sh 机读静默漏）。

阶段五：验证

写入后读回每个文件，确认：

• 没有残留的 [待定义]、[项目名称]、[一句话描述] 等占位符（docs/context/ 的 [待填]/待定 是探索期合法状态，不算残留，不阻断配置完成）
• ARCHITECTURE.md 的分层与实际目录结构一致（如果有代码）
• CLAUDE.md 的技术栈与实际依赖一致（如果有 package.json）

阶段六：引导进入开发

"配置完成。告诉我你想做的第一个功能吧。"

---

RUBRIC 渐进式积累

配置向导只生成 RUBRIC 的基础框架。后续标准通过以下方式自然积累：

• 用户纠正 AI 时：AI 把用户的纠正整理为惩罚项，用 Edit 追加到 RUBRIC.md
• 用户表示认可时：AI 把认可的模式整理为奖励项，用 Edit 追加到 RUBRIC.md
• 设计阶段做决策时：影响全局的决策记入 RUBRIC（如"本项目统一用 Server Components"）

触发条件：用户说了类似"不要这样"、"以后都这样做"、"这个方向对"等反馈时，AI 判断是否值得写入 RUBRIC，值得就写入并告知用户"我把这个记到了项目标准里"。

注意事项

• 逐项对话，不要一次性抛出所有问题。每项等用户回答后再下一项。
• 推断结果必须给用户确认。用户可能 fork 了别人的项目，推断不一定准确。
• 不要编造标准。用户没说过的偏好不要写入 RUBRIC。"没有"也是合法答案，后续积累即可。
• 所有关键决策用户拍板。AI 提供推荐方案和理由，用户选择或提出自己的方案。
• 用户的选择优先于 AI 的推荐。即使 AI 认为另一个方案更好，如果用户坚持，尊重用户。可以说明风险，但不要反复劝说。