用途
Project Scaffolding 用于为任意项目生成完整的 CLAUDE.md 和 .claude/ 目录结构，让 AI 智能体从第一次会话起就获得有效工作所需的上下文——构建命令、约定、质量门禁和会话跟踪。
技术栈检测
在脚手架生成之前，通过扫描清单文件检测项目技术栈：
| 发现的文件 | 检测到的技术栈 | 构建工具 |
|---|---|---|
| tsconfig.json | TypeScript | tsc, npm/yarn/pnpm |
| package.json（无 tsconfig） | JavaScript | npm/yarn/pnpm |
| pyproject.toml | Python | pip/poetry/uv |
| setup.py 或 requirements.txt | Python（旧式） | pip |
| Cargo.toml | Rust | cargo |
| go.mod | Go | go |
| Makefile | 检查内容 | 视情况而定 |
| Dockerfile | 容器 | docker |
检测步骤：列出项目根目录文件，检查上述清单文件；若存在 package.json，读取 scripts 以查找构建/测试/lint 命令；若存在 pyproject.toml，读取 [tool] 段以了解已配置工具；若检测到多个技术栈，全部记录（monorepo 模式）。
CLAUDE.md 生成
使用 references/claude-md-template.md 中的模板并填入检测到的信息，目标控制在 200 行以内。Claude Code 在系统提示中会在约 200 行后截断 CLAUDE.md，因此需保持精简。
内容包括：项目概览（读取 README.md 或 package.json 描述）；构建与运行命令（从清单 scripts 段检测，保留 8-10 个最常用命令，并注明“完整列表见 [manifest]”）；Triggers（将文件模式映射到文档/技能，用于按需加载深层上下文）；命名约定（根据技术栈从 references/naming-conventions.md 选择，若表格较大则移至 docs/CONVENTIONS.md 并从 Triggers 引用）；测试命令（检测或询问用户）；Lint 命令（检测或询问用户）。
预填内容：核心行为（含自我改进与并行会话规则）、Triggers 段（根据检测到的项目结构生成）、测试优先开发规则、Git 提交规则（conventional commits）、禁止文件（.env、credentials、node_modules 等）、环境变量规则。
需要检测或用户输入的内容：项目名称与描述、构建/测试/lint/dev 命令、技术栈相关命名约定、用户想要的任何自定义约定。
Triggers 生成
Triggers 段将文件模式映射到更深入的文档，实现按需加载上下文而不使 CLAUDE.md 膨胀。
生成方法：扫描项目结构中的不同目录（如 src/、lib/、tests/、docs/）；识别现有文档文件（docs/*.md、ARCHITECTURE.md、CONTRIBUTING.md）；将每个源目录映射到最相关的文档或技能；包含标准模式：Dockerfile → 部署文档，tests/ → 测试文档，新文件 → 约定。
示例生成的 Triggers：
| 文件模式 | 加载 |
|---|---|
| src/api/* | Read: docs/API.md |
| src/components/* | Read: docs/COMPONENTS.md |
| tests/* | Read: docs/TESTING.md |
| Dockerfile, docker-compose* | Read: docs/DEPLOYMENT.md |
| 新建 .ts 文件 | Read: docs/CONVENTIONS.md |
若尚无文档，则在脚手架生成期间创建带 TODO 占位符的存根文档文件。
MEMORY.md 初始化
用检测到的技术栈的初始经验填充项目的 MEMORY.md。MEMORY.md 会自动加载到每个 Claude Code 系统提示中，形成自我改进循环。
位置：~/.claude/projects/<project-path-with-dashes>/memory/MEMORY.md，其中 <project-path-with-dashes> 是绝对项目路径将 / 替换为 -（例如 -Users-dev-myproject）。
填充内容：技术栈详情（语言版本、构建工具、包管理器）；架构模式（检测期间发现的模块结构）；检测到的技术栈的常见陷阱——TypeScript：ESM 导入扩展名、tsconfig 严格性、仅类型导入；Python：虚拟环境激活、init.py 要求、使用 mypy 进行类型检查；Rust：借用检查器常见错误、特性标志、工作区模式；Go：模块路径、导出与未导出、错误包装；测试模式（框架、mock 策略、测试文件位置）；所有者偏好（用户在 /init 期间指定的任何约定）。
大小预算：初始保持在 55 行以内，为智能体在会话中学习留出增长空间。200 行系统提示限制同样适用于 MEMORY.md。
目录结构创建
创建以下结构：
.claude/ ├── commands/ │ └── parallel.md ← 多会话协调指南 ├── reports/ │ ├── _registry.md ← 来自 session-management 参考 │ ├── _tech-debt.md ← 来自 session-management 参考 │ ├── architecture/ │ ├── bugs/ │ ├── code-review/ │ ├── config/ │ ├── dependencies/ │ ├── docs/ │ ├── features/ │ ├── integration/ │ ├── performance/ │ ├── refactor/ │ ├── security/ │ ├── testing/ │ ├── ci/ │ ├── tech-debt/ │ └── release/ └── scripts/ └── post-edit-check.sh ← 来自 quality-gates 钩子
步骤：在 .claude/reports/ 下创建全部 15 个类别目录；将 registry-template.md 内容复制到 .claude/reports/_registry.md（空，可直接使用）；将 tech-debt-template.md 内容复制到 .claude/reports/_tech-debt.md（空，可直接使用）；通过 Bash 使用 cp 将 post-edit-check.sh 复制到 .claude/scripts/（不要使用 Write 工具——Write 可能损坏行尾并破坏脚本）：
mkdir -p .claude/scripts && cp "$CLAUDE_PLUGIN_DIR/scripts/post-edit-check.sh" .claude/scripts/post-edit-check.sh && chmod +x .claude/scripts/post-edit-check.sh
若 $CLAUDE_PLUGIN_DIR 不可用，通过 find ~/.claude -name "post-edit-check.sh" | head -1 定位插件并从中 cp。
创建 .claude/commands/parallel.md，包含项目特定的文件所有权边界；在自动记忆路径初始化 MEMORY.md（见上文 MEMORY.md 初始化部分）。
钩子设置
根据检测到的技术栈，配置 PostToolUse 钩子。创建或更新 .claude/settings.json，内容必须完全如下（无额外参数、无修改）：
{ "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "bash .claude/scripts/post-edit-check.sh" } ] } ] } }
重要：命令必须完全为 bash .claude/scripts/post-edit-check.sh——不要添加诸如 $CLAUDE_TOOL_INPUT_FILE_PATH 之类的参数。脚本会自动从环境读取 $CLAUDE_TOOL_INPUT。
不要修改脚本——它已通过文件扩展名检测处理所有技术栈（TypeScript、Python、Rust、Go）。原样复制。
交互流程
运行脚手架时，与用户交互以做出决策：
步骤 1：检测并确认——显示检测到的技术栈、构建、测试、Lint 命令，询问是否正确、是否需要更改。
步骤 2：自定义约定——询问是否有项目特定约定应添加到 CLAUDE.md，例如特定目录结构规则、必需代码模式、禁止模式或反模式。
步骤 3：生成并审查——生成包含所有检测到及用户提供信息的 CLAUDE.md；创建 .claude/ 目录结构；设置钩子；显示所创建内容的摘要。
步骤 4：确认——列出已创建内容：CLAUDE.md（含 Triggers 的项目配置，200 行以内）、.claude/reports/（15 个类别目录 + registry + 技术债务跟踪器）、.claude/commands/parallel.md（多会话协调）、.claude/scripts/post-edit-check.sh（自动验证钩子）、.claude/settings.json（已接入 PostToolUse 钩子）、MEMORY.md（初始化于 ~/.claude/projects/.../memory/MEMORY.md）。
交叉引用
references/claude-md-template.md——完整的 CLAUDE.md 模板，含占位符段落 references/naming-conventions.md——语言特定命名表（TS、Py、Rust、Go） references/git-workflow.md——Conventional commits、分支和 PR 模式
适用场景与限制
适用于需要为项目快速建立 AI 智能体工作上下文的场景，支持 TypeScript、JavaScript、Python、Rust、Go 等主流技术栈及 monorepo。限制：CLAUDE.md 与 MEMORY.md 均受约 200 行系统提示截断限制，需保持精简；钩子命令与脚本内容不可修改；部分信息（项目名称、描述、自定义约定等）需用户输入或检测确认。