project-setup

project-setup

在当前项目中部署完整的 SDD 架构，并配置 engram 持久化和 ai-context/ 记忆层。

触发方式：/project-setup、/project-setup --interactive、初始化项目、设置 SDD、配置 Claude 项目、新建 SDD 项目、引导初始化 Claude、创建项目 CLAUDE.md

---

此技能的功能

用户运行 /project-setup 时，我会分析当前项目并生成：

1. 项目根目录下包含实际检测到的上下文的 CLAUDE.md
2. 初始化了 5 个记忆文件的 ai-context/
3. SDD 周期的 Engram 项目上下文
4. 根据检测到的技术栈整理的相关技能注册表

---

流程

步骤 0 — 选择模式

project-setup 有两种运行模式：

• 自动模式（默认） — 无需提问，完整部署。检测技术栈并生成 CLAUDE.md + 5 个 ai-context/ 文件 + Engram 上下文。用户直接运行 /project-setup、未指定模式标记时，即采用此模式。继续执行步骤 1。
• 交互模式 — 分步向导，仅生成项目 CLAUDE.md（不部署 ai-context/），并在每个问题之间等待确认。用户运行 /project-setup --interactive、/project-setup wizard，或明确要求逐步引导创建 CLAUDE.md 时，即启用此模式。跳转到下方的交互模式，不要执行步骤 1–5。

根据调用方式选择模式。如果有歧义，只询问一次用户想要哪种模式，然后继续。两种模式不会在同一次调用中运行。

---

交互模式

这是一个需要逐步确认的引导向导，只创建一个文件：项目的 CLAUDE.md。仅运行以下步骤，绝不会继续执行自动模式的步骤 1–5。

I0 — 拒绝在错误的上下文中运行

此模式适用于 claude-config 仓库以外的项目。如果满足以下任一条件，则拒绝运行并停止：

• 当前工作目录（CWD）的目录名为 claude-config 或 agent-config。
• CWD 同时包含 install.sh 和 skills/_shared/。

输出：此模式适用于外部项目。claude-config 仓库应直接编辑自身的 CLAUDE.md。，然后停止。

I1 — 检查是否已有 CLAUDE.md

如果 CWD 根目录下已存在 CLAUDE.md，则停止并询问：

已存在 CLAUDE.md。请选择：

1. 使用 /config-audit 审查现有文件（推荐）。
2. 使用全新模板覆盖（具有破坏性）。
3. 取消。

等待用户回答。只有用户明确选择覆盖后才继续。

I2 — 定位模板

读取 ~/.claude/docs/templates/project-claude-template.md。如果文件不存在，且用户在本地克隆了 claude-config 仓库，则回退到仓库路径（~/agent-config/docs/templates/... 或 ~/claude-config/docs/...）。

如果两个路径都无法解析，则停止并告知用户先在此计算机上从 claude-config 运行 install.sh。

I3 — 检测技术栈信号

扫描项目根目录（深入一层）以查找技术栈指示文件：

文件	技术栈提示
package.json	Node.js。读取 dependencies 以进一步确定：next、react、vue、svelte、express、fastify、nest。
pyproject.toml / requirements.txt	Python。
go.mod	Go。
Cargo.toml	Rust。
pom.xml / build.gradle	Java/Kotlin。
Gemfile	Ruby。
composer.json	PHP。
mix.exs	Elixir。

还要检测测试、Lint 和构建命令。缓存检测到的信号——这些信号会预填 I4 中的答案，但不能绕过用户确认。

I4 — 提出向导的 5 个问题

每次只问一个问题。每问完一个后都停止。

Q1 — 技术栈描述：用一行描述技术栈（根据检测结果预填 ——请确认或修改）。

Q2 — 约定：此项目强制执行哪些全局层未涵盖的约定？列出 1-5 条， 或回答“无”。

Q3 — 命令：Install / Dev / Test / Lint / Type check / Build（有 package.json 脚本时根据脚本预填；留空则跳过）。

Q4 — 领域术语表：影响代码阅读的不常见领域术语 （例如“Wallet”“Reconciliation”“Tenant”）。提供 0-10 个术语及其一行定义， 或回答“无”。

Q5 — 覆盖全局规则：是否有任何全局规则需要在此项目中覆盖？写明规则 和原因，或回答“无”——覆盖应当少见且经过慎重考虑。

I5 — 渲染预览

使用模板骨架。根据答案填充占位符。删除答案为“无”或空白的章节。将渲染后的文件 放在围栏代码块中展示。询问：

确认要在项目根目录写入 CLAUDE.md 吗？（y / edit / n）

y → 写入。edit → 询问要修改哪个章节，然后返回继续。n → 中止。

I6 — 写入

在 CWD 根目录写入 CLAUDE.md。不得修改任何其他文件。文件不得超过 60 行——删除空章节，不要保留。

I7 — 写入后检查清单

打印：

Created: CLAUDE.md (<N> lines).

Recommended next steps:
  1. Review the file.
  2. Run /config-audit from this directory to check cross-layer duplication.
  3. Commit the file.

Reminders:
  - This file is the project layer. The global layer (from claude-config)
    still applies in every session.
  - Do not restate global rules here. Use the "Overrides global" section to
    deviate.

I8 — 保存到 engram

调用 mem_save：

• title: Initialized CLAUDE.md for <project name>
• type: config
• topic_key: project-init/<project-name>
• content: 包含这 5 个向导答案的结构化 What/Why/Where/Learned。

交互模式到此结束。不得继续执行步骤 1。

---

步骤 1 — 项目检测

我会读取并分析：

• package.json / pyproject.toml / go.mod / Cargo.toml / pom.xml
• 文件夹结构（src/、app/、lib/、tests/ 等）
• 配置文件（tsconfig、eslint、prettier 等）
• README.md（如果存在）
• 现有文档文件夹
• .git/，以确认这是一个仓库

我会推断：

• 主要语言及其版本
• 使用的框架
• 数据库 / ORM
• 测试工具
• 构建 / 打包工具
• 检测到的命名约定（camelCase、snake_case 等）
• 文件夹结构（按功能、按层、单体仓库等）

步骤 2 — 生成中立的指令源（AGENTS.md + Claude 垫片）

权威来源是与提供方无关的 AGENTS.md（Copilot、Cursor、Gemini、Codex 原生读取的跨工具 标准——参见 core/PORTABILITY.md § Audience/source）。我会使用 AI_CONTEXT_TEMPLATES.md 中的**“项目指令骨架（步骤 2）”** 部分，在根目录创建 AGENTS.md。根据实际检测到的上下文填写所有占位符——绝不留下 未填充的占位符。

Claude 协调（必须执行）： Claude Code 读取的是 CLAUDE.md，而不是 AGENTS.md。因此，我还会编写一个仅有 1 行的 CLAUDE.md 垫片，其唯一内容是 导入指令：

@AGENTS.md

这样，AGENTS.md 就是唯一由人工编写的真实来源，而 Claude Code 会通过导入来读取它。 （符号链接也是一种替代方案，但在 Windows 上需要管理员/开发者模式——导入垫片是跨平台的默认方案。）如果已有 旧版 CLAUDE.md 且包含实际内容，我会将其内容迁移到 AGENTS.md，并替换为垫片——绝不保留两个 彼此不一致的来源。

步骤 3 — 初始化 ai-context/

我会根据检测到的信息创建 5 个包含实际内容的文件，使用 AI_CONTEXT_TEMPLATES.md 中的 **“ai-context/ 文件（步骤 3）”**部分：stack.md、architecture.md、 conventions.md、known-issues.md、changelog-ai.md。根据步骤 1 的检测结果填写各模板中的占位符； [date] 使用今天的日期。

第 4 步 — 将项目上下文持久化到 engram

检查 Engram MCP 是否可访问（调用 mem_context）：

• 如果可访问：通过 mem_save 将项目上下文保存到 engram，并设置 topic_key: project-setup/{project-name}。记录 INFO: Engram detected — project context persisted to engram。 （这与 sdd-init 所管理的 sdd-init/{project-name} 不同——使用单独的键可避免发生 upsert 冲突，导致一个技能覆盖另一个技能的项目上下文指针。）
• 如果不可访问：记录 WARNING: Engram not available — project context not persisted. SDD artifacts will be ephemeral.

第 5 步 — 最终报告

我向用户呈现：

✅ Project configured: [name]

Detected stack:
  - [language + version]
  - [framework + version]
  - [testing framework]

Files created:
  - CLAUDE.md
  - ai-context/stack.md
  - ai-context/architecture.md
  - ai-context/conventions.md
  - ai-context/known-issues.md
  - ai-context/changelog-ai.md

Next steps:
  1. Review and adjust CLAUDE.md with details I could not detect
  2. To start a change: /sdd-explore <topic> or /sdd-propose <change-name>
  3. To create project-specific skills: /skill-create <name>

---

规则

• 绝不在未警告并征求确认的情况下覆盖现有文件
• 如果 CLAUDE.md 已存在，我会提供智能合并或创建备份的选项
• 如果 ai-context/ 已存在，我会提供仅更新缺失内容的选项
• 我始终阅读真实代码——绝不臆造技术栈
• 如果我无法确定某项内容，会将其标记为 [To confirm]
• 绝不创建 .claude/commands/ 目录——commands/ 是旧机制；.claude/skills/ 是新项目唯一受支持的扩展方式。

交互模式规则

• 绝不在 claude-config / agent-config 仓库中运行交互模式。该 仓库会直接编辑自身的 CLAUDE.md。
• 未经用户明确确认，绝不覆盖现有的 CLAUDE.md。
• 交互模式只写入一个文件：<cwd>/CLAUDE.md。此模式下绝不写入 CWD 之外的内容，也绝不通过交互模式部署 ai-context/。
• 绝不在生成的文件中重述全局规则。如果用户在向导中提供全局 规则（响应格式、验证、engram），应予以拒绝，并指向全局层。
• 每次提出向导问题后都必须停下。绝不合并提问，也绝不静默设置默认值。
• 生成的文件不得超过 60 行。删除空章节。
• 不要提交，也不要自动运行任何审计——这些由用户决定。