Project Scaffolding

项目脚手架

用途

为任意项目生成完整的 CLAUDE.md 和 .claude/ 目录结构。这能为 AI Agent 提供从首次会话起高效工作的必要上下文——构建命令、约定、质量门禁和会话跟踪。

技术栈检测

生成脚手架之前，通过扫描清单文件检测项目的技术栈：

找到的文件	检测到的技术栈	构建工具
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

检测步骤

1. 列出项目根目录中的文件：检查是否存在上述清单文件
2. 如果存在 package.json，读取 scripts 以查找构建、测试和 lint 命令
3. 如果存在 pyproject.toml，读取 [tool] 部分以查找已配置的工具
4. 如果检测到多个技术栈，记录所有技术栈（monorepo 模式）

生成 CLAUDE.md

使用 references/claude-md-template.md 中的模板，并填入检测到的信息。目标：少于 200 行。 Claude Code 会在系统提示词中将 CLAUDE.md 截断到约 200 行，因此内容应保持精简。

1. 项目概览 — 阅读 README.md 或 package.json 中的描述
2. 构建和运行命令 — 从清单文件的 scripts 部分检测（保留最常用的 8-10 条，并添加“完整列表参见 [清单文件]”）
3. 触发器 — 将文件模式映射到文档/技能，以便按需加载深入上下文
4. 命名约定 — 根据技术栈从 references/naming-conventions.md 中选择。如果表格较大，则移至 docs/CONVENTIONS.md，并在触发器中引用
5. 测试命令 — 检测或询问用户
6. Lint 命令 — 检测或询问用户

预先填充的内容

• 核心行为（包括自我改进和并行会话规则）
• 触发器部分（根据检测到的项目结构生成）
• 测试优先开发规则
• Git 提交规则（约定式提交）
• 禁止文件（.env、凭据、node_modules 等）
• 环境变量规则

需要检测或由用户提供的内容

• 项目名称和描述
• 构建、测试、lint 和开发命令
• 特定技术栈的命名约定
• 用户希望采用的任何自定义约定

生成触发器

触发器部分将文件模式映射到更深入的文档，从而按需加载上下文，而不会让 CLAUDE.md 变得臃肿。

如何生成触发器

1. 扫描项目结构，找出不同的目录（例如 src/、lib/、tests/、docs/）
2. 找出现有文档文件（docs/*.md、ARCHITECTURE.md、CONTRIBUTING.md）
3. 将每个源代码目录映射到最相关的文档或技能
4. 包含标准模式：Dockerfile → 部署文档，tests/ → 测试文档，新文件 → 约定

生成的触发器示例

| File Pattern | Load |
|---|---|
| src/api/* | Read: docs/API.md |
| src/components/* | Read: docs/COMPONENTS.md |
| tests/* | Read: docs/TESTING.md |
| Dockerfile, docker-compose* | Read: docs/DEPLOYMENT.md |
| New .ts files | 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）。

要植入的内容

1. 技术栈详情 — 语言版本、构建工具、包管理器
2. 架构模式 — 检测过程中发现的模块结构
3. 检测到的技术栈的常见问题：
   • TypeScript：ESM 导入扩展名、tsconfig 严格性、仅类型导入
   • Python：虚拟环境激活、__init__.py 要求、使用 mypy 进行类型检查
   • Rust：借用检查器常见错误、功能标志、工作区模式
   • Go：模块路径、导出与未导出、错误封装
4. 测试模式 — 测试框架、模拟策略、测试文件位置
5. 所有者偏好 — 用户在 /init 期间指定的任何约定

大小限制

初始内容保持在 55 行以内，为 Agent 在会话期间逐步积累内容留出空间。200 行的系统提示词限制同样适用于 MEMORY.md。

创建目录结构

创建以下结构：

.claude/
├── commands/
│   └── parallel.md            ← multi-session coordination guide
├── reports/
│   ├── _registry.md          ← from session-management references
│   ├── _tech-debt.md         ← from session-management references
│   ├── architecture/
│   ├── bugs/
│   ├── code-review/
│   ├── config/
│   ├── dependencies/
│   ├── docs/
│   ├── features/
│   ├── integration/
│   ├── performance/
│   ├── refactor/
│   ├── security/
│   ├── testing/
│   ├── ci/
│   ├── tech-debt/
│   └── release/
└── scripts/
    └── post-edit-check.sh     ← from quality-gates hook

步骤

1. 在 .claude/reports/ 下创建全部 15 个类别目录
2. 将 registry-template.md 的内容复制到 .claude/reports/_registry.md（空文件，可直接使用）
3. 将 tech-debt-template.md 的内容复制到 .claude/reports/_tech-debt.md（空文件，可直接使用）
4. 使用 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 定位插件，然后从该位置复制。
5. 创建 .claude/commands/parallel.md，并在其中定义项目特定的文件所有权边界
6. 在自动记忆路径下创建 MEMORY.md 初始内容（参见上文的 MEMORY.md 初始设置部分）

Hook 设置

根据检测到的技术栈，配置 PostToolUse hook：

1. 创建或更新 .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。

2. 请勿修改脚本 — 它已通过文件扩展名检测处理所有技术栈（TypeScript、Python、Rust、Go）。请原样复制。

交互流程

运行脚手架时，请与用户互动以确定相关选项：

步骤 1：检测并确认

Detected stack: TypeScript (package.json + tsconfig.json)
Build: npm run build
Test: npm test
Lint: npm run lint

Does this look correct? Any changes?

步骤 2：自定义约定

Any project-specific conventions I should add to CLAUDE.md?
For example:
- Specific directory structure rules
- Required code patterns
- Forbidden patterns or anti-patterns

步骤 3：生成并审查

1. 根据所有检测到的信息和用户提供的信息生成 CLAUDE.md
2. 创建 .claude/ 目录结构
3. 设置 hook
4. 显示已创建内容的摘要

步骤 4：确认

Created:
- CLAUDE.md (project configuration with Triggers, under 200 lines)
- .claude/reports/ (15 category dirs + registry + tech debt tracker)
- .claude/commands/parallel.md (multi-session coordination)
- .claude/scripts/post-edit-check.sh (auto-validation hook)
- .claude/settings.json (PostToolUse hook wired up)
- MEMORY.md (seeded at ~/.claude/projects/.../memory/MEMORY.md)

Ready to start developing with session tracking, auto-validation,
and self-improvement across sessions.

交叉引用

• references/claude-md-template.md — 包含占位章节的完整 CLAUDE.md 模板
• references/naming-conventions.md — 特定语言的命名表（TS、Py、Rust、Go）
• references/git-workflow.md — Conventional Commits、分支和 PR 模式