project-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

project-setup

项目设置

Deploys the complete SDD architecture with engram persistence and ai-context/ memory layer in the current project.

Triggers:

/project-setup

/project-setup --interactive

, initialize project, setup sdd, configure claude project, new sdd project, bootstrap claude, create project CLAUDE.md

在当前项目中部署完整的SDD架构，包含engram持久化和ai-context/内存层。

触发指令：

/project-setup

、

/project-setup --interactive

、initialize project、setup sdd、configure claude project、new sdd project、bootstrap claude、create project CLAUDE.md

What this skill does

该技能的功能

When the user runs

/project-setup

, I analyze the current project and generate:

```
CLAUDE.md
```
at the project root with real detected context
```
ai-context/
```
with the 5 memory files initialized
Engram project context for the SDD cycle
Registry of relevant skills based on the detected stack

当用户运行

/project-setup

时，我会分析当前项目并生成：

项目根目录下带有真实检测上下文的
```
CLAUDE.md
```
文件
已初始化5个内存文件的
```
ai-context/
```
目录
用于SDD周期的Engram项目上下文
基于检测到的技术栈生成的相关技能注册表

Process

流程

Step 0 — Mode select

步骤0 — 模式选择

project-setup

runs in one of two modes:

Automatic (default) — zero-question full deploy. Detect the stack and generate
```
CLAUDE.md
```
+ the five
```
ai-context/
```
files + engram context. This is the behavior when the user runs
```
/project-setup
```
with no mode flag. Proceed to Step 1.
Interactive — a guided wizard that produces ONLY a project
```
CLAUDE.md
```
(no
```
ai-context/
```
deploy), with stop-between-question confirmation. Triggered when the user runs
```
/project-setup --interactive
```
,
```
/project-setup wizard
```
, or explicitly asks to be walked through CLAUDE.md creation. Jump to Interactive mode below and do NOT run Steps 1-5.

Pick the mode from the invocation. If ambiguous, ask once which mode the user wants, then proceed. The two modes never run in the same invocation.

project-setup

支持两种运行模式：

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

根据调用指令选择模式。若指令模糊，询问一次用户想要的模式后再继续。两种模式不会在同一次调用中运行。

Interactive mode

交互式模式

A guided, confirmation-gated wizard that creates exactly one file: the project

CLAUDE.md

. Runs ONLY the steps below — it never falls through to the automatic Steps 1-5.

这是一个带确认机制的引导式向导，仅创建一个文件：项目

CLAUDE.md

。仅执行以下步骤 — 绝不会自动执行步骤1-5。

I0 — Refuse to run in the wrong context

I0 — 拒绝在错误环境中运行

This mode is for projects OTHER than the

claude-config

repo. Refuse and stop if any of these is true:

CWD basename is
```
claude-config
```
or
```
agent-config
```
.
CWD contains both
```
install.sh
```
and
```
skills/_shared/
```
.

Print:

This mode is for external projects. The claude-config repo edits its own CLAUDE.md directly.

and stop.

此模式适用于

claude-config

仓库以外的项目。若出现以下任一情况，拒绝执行并停止：

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

输出：

此模式适用于外部项目。claude-config仓库需直接编辑自身的CLAUDE.md文件。

并停止。

I1 — Check for existing

CLAUDE.md

I1 — 检查是否存在

CLAUDE.md

CLAUDE.md

already exists at CWD root, STOP and ask:

A
CLAUDE.md
already exists. Choose one:
Audit the existing file with
/config-audit
(recommended).
Overwrite with a fresh template (destructive).

Cancel.

Wait for the answer. Only proceed if the user explicitly picks overwrite.

CLAUDE.md

，停止并询问：

已存在
CLAUDE.md
文件。请选择：
使用
/config-audit
审核现有文件（推荐）。
用新模板覆盖（会覆盖原有内容）。

取消。

等待用户回复。仅当用户明确选择覆盖时才继续。

I2 — Locate the template

I2 — 定位模板

Read

~/.claude/docs/templates/project-claude-template.md

. If missing, fall back to the repo path if the user has the

claude-config

repo cloned locally (

~/agent-config/docs/templates/...

~/claude-config/docs/...

If neither path resolves, STOP and tell the user to run

install.sh

from

claude-config

on this machine first.

读取

~/.claude/docs/templates/project-claude-template.md

。若文件不存在，且用户本地克隆了

claude-config

仓库，则回退到仓库路径（

~/agent-config/docs/templates/...

或

~/claude-config/docs/...

）。

若两个路径都无法找到，停止并告知用户先在本机运行

claude-config

仓库中的

install.sh

。

I3 — Detect stack signals

I3 — 检测技术栈信号

Scan the project root (one level deep) for stack indicators:

File present	Stack hint
`package.json`	Node.js. Read `dependencies` to refine: 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.

Also detect test/lint/build commands. Cache the detected signals — they prefill answers in I4 but do NOT bypass user confirmation.

扫描项目根目录（一级深度）以识别技术栈指标：

存在的文件	技术栈提示
`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。

同时检测测试/代码检查/构建命令。缓存检测到的信号 — 这些信号会预填充I4中的答案，但不会跳过用户确认步骤。

I4 — Ask the 5 wizard questions

I4 — 询问5个向导问题

Ask one at a time. STOP after each.

Q1 — Stack description: one-line stack description (prefilled from detection — confirm or edit).

Q2 — Conventions: what conventions does this project enforce that the global layer does not cover? 1-5 bullets, or "none".

Q3 — Commands: Install / Dev / Test / Lint / Type check / Build (prefilled from

package.json

scripts where available; leave blank to skip).

Q4 — Domain glossary: non-obvious domain terms that affect code reading (e.g. "Wallet", "Reconciliation", "Tenant"). 0-10 terms with one-line definitions, or "none".

Q5 — Overrides global: any global rule to override for this project? Name the rule and the reason, or "none" — overrides should be rare and deliberate.

逐个提问，每个问题后等待回复。

问题1 — 技术栈描述：一行技术栈描述（从检测结果预填充 — 确认或编辑）。

问题2 — 约定规范：此项目强制执行哪些全局层未覆盖的约定？1-5个要点，或回答“无”。

问题3 — 命令：安装/开发/测试/代码检查/类型检查/构建命令（若可用则从

package.json

脚本预填充；留空则跳过）。

问题4 — 领域术语表：影响代码阅读的非通用领域术语（例如“Wallet”、“Reconciliation”、“Tenant”）。0-10个带一行定义的术语，或回答“无”。

问题5 — 全局规则覆盖：是否需要为此项目覆盖任何全局规则？说明规则名称和原因，或回答“无” — 覆盖操作应谨慎且少见。

I5 — Render preview

I5 — 渲染预览

Use the template skeleton. Fill placeholders with the answers. Drop any section answered "none" or blank. Show the rendered file in a fenced code block. Ask:

Confirm to write
CLAUDE.md
at the project root? (y / edit / n)

→ write.

edit

→ ask which section, loop back.

→ abort.

使用模板框架，用用户的回答填充占位符。删除回答为“无”或空白的部分。在代码块中显示渲染后的文件，并询问：

确认在项目根目录写入
CLAUDE.md
吗？(y / 编辑 / n)

→ 写入文件。

edit

→ 询问要编辑的部分，循环返回。

→ 终止操作。

I6 — Write

I6 — 写入文件

Write

CLAUDE.md

at CWD root. Do NOT touch any other file. Keep the file under 60 lines — empty sections are dropped, not preserved.

CLAUDE.md

。不得修改任何其他文件。文件行数控制在60行以内 — 空部分直接删除，不保留。

I7 — Post-write checklist

I7 — 写入后检查清单

Print:

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.

输出：

已创建：CLAUDE.md（共<N>行）。

推荐后续步骤：
  1. 查看文件内容。
  2. 在此目录运行/config-audit检查跨层重复内容。
  3. 提交该文件。

提示：
  - 此文件为项目层配置。全局层配置（来自claude-config）在每次会话中仍会生效。
  - 请勿在此重复全局规则。如需偏离全局规则，请使用“全局规则覆盖”部分。

I8 — Save to engram

I8 — 保存到Engram

Call

mem_save

title:

Initialized CLAUDE.md for <project name>

type:
```
config
```
topic_key:
```
project-init/<project-name>
```
content: structured What/Why/Where/Learned with the 5 wizard answers.

Interactive mode ends here. Do NOT continue to Step 1.

调用

mem_save

：

title:

Initialized CLAUDE.md for <project name>

type:
```
config
```
topic_key:
```
project-init/<project-name>
```
content: 包含5个向导问题答案的结构化What/Why/Where/Learned内容。

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

Step 1 — Project detection

步骤1 — 项目检测

I read and analyze:

package.json

pyproject.toml

go.mod

Cargo.toml

pom.xml

Folder structure (src/, app/, lib/, tests/, etc.)
Configuration files (tsconfig, eslint, prettier, etc.)
README.md if it exists
Existing docs folders
```
.git/
```
to confirm it is a repository

I infer:

Main language and version
Framework(s) in use
Database / ORM
Testing tools
Build / bundler tools
Detected naming conventions (camelCase, snake_case, etc.)
Folder structure (feature-based, layer-based, monorepo, etc.)

我会读取并分析：

package.json

pyproject.toml

go.mod

Cargo.toml

pom.xml

文件夹结构（src/、app/、lib/、tests/等）
配置文件（tsconfig、eslint、prettier等）
若存在则读取README.md
现有文档文件夹
```
.git/
```
以确认这是一个代码仓库

我会推断：

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

Step 2 — Generate the neutral instruction source (

AGENTS.md

+ Claude shim)

步骤2 — 生成中立指令源（

AGENTS.md

+ Claude适配层）

The source-of-truth is the provider-neutral AGENTS.md
(the cross-tool standard read natively by Copilot, Cursor, Gemini, Codex — see

core/PORTABILITY.md

§ Audience/source). I create

AGENTS.md

at the root using the "Project instruction skeleton (Step 2)" section of

AI_CONTEXT_TEMPLATES.md

. Fill every placeholder with real detected context — never ship a placeholder unresolved.

Claude reconciliation (mandatory): Claude Code reads

CLAUDE.md

, not

AGENTS.md

. So I ALSO write a 1-line

CLAUDE.md

shim whose only content is the import directive:

@AGENTS.md

This keeps

AGENTS.md

the single hand-authored truth while Claude Code loads it via import. (Symlink is an alternative but needs Admin/Developer Mode on Windows — the import shim is the cross-platform default.) If a legacy

CLAUDE.md

already holds real content, I migrate its content into

AGENTS.md

and replace it with the shim — I never leave two divergent sources.

权威来源是供应商中立的**

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

。因此我还会写入一行

CLAUDE.md

适配层，内容仅为导入指令：

@AGENTS.md

这样既保持

AGENTS.md

为唯一人工维护的权威文件，同时Claude Code可通过导入加载它。（符号链接是另一种方案，但在Windows上需要管理员/开发者模式 — 导入适配层是跨平台默认方案。）若已有包含真实内容的旧版

CLAUDE.md

，我会将其内容迁移到

AGENTS.md

，并替换为适配层 — 绝不会保留两个不一致的来源。

Step 3 — Initialize ai-context/

步骤3 — 初始化ai-context/

I create the 5 files with real content based on what was detected, using the "
ai-context/
files (Step 3)" section of

AI_CONTEXT_TEMPLATES.md

stack.md

architecture.md

conventions.md

known-issues.md

changelog-ai.md

. Each template's placeholders are filled from Step 1 detection;

[date]

is today's date.

我会基于检测到的内容创建5个包含真实内容的文件，使用

AI_CONTEXT_TEMPLATES.md

中的**“

ai-context/

文件（步骤3）”**部分：

stack.md

、

architecture.md

、

conventions.md

、

known-issues.md

、

changelog-ai.md

。每个模板的占位符用步骤1的检测结果填充；

[date]

替换为当前日期。

Step 4 — Persist project context to engram

步骤4 — 将项目上下文持久化到Engram

Check if Engram MCP is reachable (call

mem_context

If reachable: save project context to engram via
```
mem_save
```
with
```
topic_key: project-setup/{project-name}
```
. Log
```
INFO: Engram detected — project context persisted to engram
```
. (Distinct from
```
sdd-init/{project-name}
```
, which
```
sdd-init
```
owns — using a separate key prevents an upsert collision where one skill overwrites the other's project-context pointer.)

If not reachable: log

WARNING: Engram not available — project context not persisted. SDD artifacts will be ephemeral.

检查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}
```
区分开 — 使用独立键可避免一个技能覆盖另一个技能的项目上下文指针的更新冲突。）

若不可达：输出日志

WARNING: Engram not available — project context not persisted. SDD artifacts will be ephemeral.

Step 5 — Final report

步骤5 — 最终报告

I present to the user:

✅ 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/stack.md
  - ai-context/architecture.md
  - ai-context/conventions.md
  - ai-context/known-issues.md
  - ai-context/changelog-ai.md

后续步骤：
  1. 查看并调整CLAUDE.md中我无法检测到的细节
  2. 若要开始变更：/sdd-explore <主题> 或 /sdd-propose <变更名称>
  3. 若要创建项目专属技能：/skill-create <名称>

Rules

规则

NEVER overwrite existing files without warning and asking for confirmation
If
```
CLAUDE.md
```
already exists, I offer an intelligent merge or creating a backup
If
```
ai-context/
```
already exists, I offer to update only what is missing
I always read real code — I never invent the stack
If I cannot determine something with certainty, I mark it as
```
[To confirm]
```
NEVER create a
```
.claude/commands/
```
directory — commands/ is a legacy mechanism;
```
.claude/skills/
```
is the only supported extensibility path for new projects.

绝不未经警告和用户确认就覆盖现有文件
若
```
CLAUDE.md
```
已存在，我会提供智能合并或创建备份的选项
若
```
ai-context/
```
已存在，我会仅更新缺失的内容
我始终读取真实代码 — 绝不虚构技术栈
若无法确定某些内容，我会标记为
```
[待确认]
```
绝不创建
```
.claude/commands/
```
目录 — commands/是旧机制；
```
.claude/skills/
```
是新项目唯一支持的扩展路径。

Interactive mode rules

交互式模式规则

NEVER run interactive mode in the
```
claude-config
```
/
```
agent-config
```
repo. That repo edits its own
```
CLAUDE.md
```
directly.
NEVER overwrite an existing
```
CLAUDE.md
```
without explicit user confirmation.
Interactive mode writes exactly one file:
```
<cwd>/CLAUDE.md
```
. Never write outside CWD in this mode, and never deploy
```
ai-context/
```
from interactive mode.
NEVER restate global rules in the generated file. If the user offers global rules during the wizard (response format, verification, engram), refuse and point to the global layer.
Stop after every wizard question. Never bundle. Never default silently.
Keep the generated file under 60 lines. Empty sections are dropped.
Do not commit and do not run any audit automatically — those are the user's decisions.

绝不在
```
claude-config
```
/
```
agent-config
```
仓库中运行交互式模式。该仓库需直接编辑自身的
```
CLAUDE.md
```
文件。
绝不未经用户明确确认就覆盖现有
```
CLAUDE.md
```
文件。
交互式模式仅写入一个文件：
```
<当前工作目录>/CLAUDE.md
```
。在此模式下绝不在当前工作目录外写入文件，也绝不部署
```
ai-context/
```
。
绝不在生成的文件中重复全局规则。若用户在向导过程中提及全局规则（响应格式、验证、Engram），拒绝并引导至全局层配置。
每个向导问题后都要停止。绝不批量提问。绝不默认静默执行。
生成的文件行数控制在60行以内。空部分直接删除。
不自动提交文件或运行审核 — 这些由用户决定。

project-setup

Original

Translation

project-setup

项目设置

What this skill does

该技能的功能

Process

流程

Step 0 — Mode select

步骤0 — 模式选择

Interactive mode

交互式模式

I0 — Refuse to run in the wrong context

I0 — 拒绝在错误环境中运行

I1 — Check for existing CLAUDE.md

I1 — 检查是否存在CLAUDE.md

I2 — Locate the template

I2 — 定位模板

I3 — Detect stack signals

I3 — 检测技术栈信号

I4 — Ask the 5 wizard questions

I4 — 询问5个向导问题

I5 — Render preview

I5 — 渲染预览

I6 — Write

I6 — 写入文件

I7 — Post-write checklist

I7 — 写入后检查清单

I8 — Save to engram

I8 — 保存到Engram

Step 1 — Project detection

步骤1 — 项目检测

Step 2 — Generate the neutral instruction source (AGENTS.md + Claude shim)

步骤2 — 生成中立指令源（AGENTS.md + Claude适配层）

Step 3 — Initialize ai-context/

步骤3 — 初始化ai-context/

Step 4 — Persist project context to engram

步骤4 — 将项目上下文持久化到Engram

Step 5 — Final report

步骤5 — 最终报告

Rules

规则

Interactive mode rules

交互式模式规则

I1 — Check for existing
`CLAUDE.md`

I1 — 检查是否存在
`CLAUDE.md`

Step 2 — Generate the neutral instruction source (
`AGENTS.md`
+ Claude shim)

步骤2 — 生成中立指令源（
`AGENTS.md`
+ Claude适配层）