09 - 脚手架设计

状态：冻结（2026-03） — CLI 工具 ai-dev-cli 不再积极维护。推荐直接使用 .claude/skills/ 中的 Skills，功能更强且无需同步维护。本文档保留作为设计参考。

1. 定位

不只是一次性初始化脚本，而是贯穿项目全生命周期的体系管理工具。

三种运行模式：

模式	命令	场景	频率
init	`npx ai-dev-cli init`	新项目初始化、已有项目接入	一次
check	`npx ai-dev-cli check`	合规审计，检查体系配置和代码规范	随时、CI 中
takeover	`npx ai-dev-cli takeover`	接手现有项目，分析代码生成 CLAUDE.md	接手时一次

设计目标：

5 分钟可用 — 运行脚本，回答几个问题，立刻开始工作
渐进式 — 初始化后可以逐步添加更多功能
幂等 — 重复运行不会覆盖已有配置
可审计 — check 模式可在 CI 中运行，输出机器可读的检查报告

2. 三种模式详解

2.1 init 模式 — 建立体系

bash

npx ai-dev-cli init                          # 交互式
npx ai-dev-cli init --level 2                # 直接指定级别
npx ai-dev-cli init --database prisma-sqlite # 指定数据库方案

执行流程：

1. 检查前置条件（git、node、claude 是否安装）
2. 交互式问答：项目名称 → 数据库方案选择 → 初始化级别
3. 生成文件（不覆盖已存在的文件，模板变量按数据库方案渲染）
4. 输出下一步操作提示

数据库方案选项（--database 参数或交互选择）：

选项	说明
`prisma-sqlite`	Prisma + SQLite，零配置本地开发（默认）
`prisma-pg`	Prisma + PostgreSQL，传统关系型数据库
`supabase-cloud`	Supabase Cloud，BaaS（含 Auth/Storage/Realtime）
`supabase-cn`	Supabase 国内自托管

不同方案影响 Level 0 CLAUDE.md 中的技术栈描述、数据库命令、架构目录、边界规则，以及 Level 3 的依赖白名单。

2.2 check 模式 — 合规审计

bash

npx ai-dev-cli check             # 完整检查
npx ai-dev-cli check --fix       # 检查并自动修复可修复项
npx ai-dev-cli check --ci        # CI 模式，非零退出码表示不合规

检查项分为两类：

基础设施检查（脚本可做，不需要 AI）：

[基础] CLAUDE.md 是否存在
[基础] .claude/settings.json 是否存在且格式正确
[基础] .claude/settings.json 是否配置了 deny 规则
[基础] Hooks 脚本是否存在且有执行权限
[基础] .gitignore 是否包含 CLAUDE.local.md 等条目
[基础] .env 文件是否被 git 追踪（不应该被追踪）

代码规范检查（脚本可做的确定性检查）：

[规范] 是否存在超过 300 行的 .ts/.tsx 文件
[规范] 是否存在 TypeScript any 类型（grep 'any' 粗筛）
[规范] 是否存在 default export（grep 'export default' 粗筛）
[规范] package.json 中是否有禁止的依赖（moment/jquery/lodash 整包）
[规范] 是否存在 .env 文件未加入 .gitignore

输出格式：

====== AI Dev Lifecycle Check ======

[PASS] CLAUDE.md 存在
[PASS] .claude/settings.json 格式正确
[PASS] deny 规则已配置
[FAIL] Hook 脚本缺少执行权限: .claude/hooks/pre-bash-firewall.sh
[WARN] 发现 2 个超过 300 行的文件:
       - src/components/Dashboard.tsx (412 行)
       - src/services/auth.service.ts (328 行)
[WARN] 发现 3 处 any 类型使用:
       - src/lib/utils.ts:42
       - src/services/api.ts:15
       - src/services/api.ts:23
[PASS] 无禁止依赖
[FAIL] .env 文件被 git 追踪

结果: 8 passed, 2 failed, 2 warnings

--fix 模式可自动修复的项：

Hook 脚本加执行权限
.gitignore 追加缺失条目
缺失的基础配置文件提示用户运行 npx ai-dev-cli init

--ci 模式：有 FAIL 项时退出码非零，可集成到 GitHub Actions。

2.3 takeover 模式 — 接管现有项目

bash

npx ai-dev-cli takeover           # 分析项目并生成配置

执行流程：

1. 扫描项目结构，识别技术栈
   - 检测 package.json → 识别框架和依赖
   - 检测目录结构 → 识别架构模式
   - 检测现有配置 → .eslintrc, tsconfig, prettier 等
2. 生成 CLAUDE.md 草稿
   - 从 package.json 提取命令（scripts 字段）
   - 从目录结构生成架构描述
   - 从现有依赖生成 approved-deps.md
3. 生成 .claude/settings.json（基于现有工具链）
4. 输出分析报告，提示人工确认和补充

关键原则：生成的是草稿，不是最终版。人必须审阅并补充业务上下文。

3. 初始化级别

Level 0 — 最小可用（约 5 分钟）

生成文件：

CLAUDE.md                       # 项目规则模板（按数据库方案渲染模板变量）
.claude/settings.json           # 基础权限配置
.gitignore 追加条目              # CLAUDE.local.md 等
docs/README.md                  # 文档导航索引
docs/features.md                # 功能清单模板
docs/prd/goals.md               # 目标与非目标
docs/prd/user-scenarios.md      # 用户场景
docs/prd/scope.md               # 范围边界
docs/prd/open-questions.md      # 开放问题追踪
docs/architecture/overview.md   # 架构概览
docs/architecture/tech-stack.md # 技术选型
docs/adr/001-template.md               # ADR 模板
docs/api/api-spec.md            # API 规范
docs/data/data-spec.md          # 数据规范
docs/approved-deps.md              # 依赖白名单（按数据库方案渲染）

CLAUDE.md 模板中由数据库方案决定的变量：TECH_STACK、DB_COMMANDS、DB_ARCHITECTURE、DB_DEPS、DB_BOUNDARY_RULE、CALL_DIRECTION。

Level 1 — 核心 Skills（在 Level 0 基础上）

追加文件：

.claude/skills/plan/SKILL.md    # /plan 需求分析
.claude/skills/review/SKILL.md  # /review 代码审查
.claude/skills/commit/SKILL.md  # /commit 智能提交

Level 2 — 质量闸门（在 Level 1 基础上）

追加文件：

.claude/hooks/pre-bash-firewall.sh    # 安全防火墙
.claude/hooks/post-edit-format.sh     # 自动格式化
.claude/hooks/pre-compact-preserve.sh # 上下文保护
.claude/hooks/post-write-size-guard.sh # 文件行数守卫
.claude/hooks/pre-bash-dep-guard.sh   # 依赖安装拦截
.claude/settings.json 追加 hooks 配置

Level 3 — 完整体系（在 Level 2 基础上）

追加文件：

.mcp.json                               # MCP 配置（Context7 + Playwright）
.claude/skills/debug/SKILL.md            # /debug 问题诊断
.claude/skills/doc/SKILL.md              # /doc 文档更新
.claude/skills/check/SKILL.md            # /check 合规体检
.claude/skills/test/SKILL.md             # /test 测试生成
.claude/skills/impact/SKILL.md           # /impact 影响分析
.claude/skills/code-standards/SKILL.md   # 编码规范（自动参考）
.claude/skills/spec/SKILL.md             # /spec 需求定义
.claude/skills/retro/SKILL.md            # /retro 会话回顾
.claude/skills/health-report/SKILL.md    # /health-report 健康度
.claude/skills/docaudit/SKILL.md         # /docaudit 文档审计
.claude/skills/takeover/SKILL.md         # /takeover 项目接管
.claude/skills/ui-page/SKILL.md          # /ui-page 页面骨架
.claude/skills/docs-site/SKILL.md        # /docs-site 文档站搭建

4. CLI 实现架构

已从 bash 脚本重写为 TypeScript CLI（ai-dev-cli），仅依赖 commander，跨平台支持 macOS/Linux/Windows。

4.1 源码目录结构

cli/
├── src/
│   ├── index.ts              # 入口：commander 注册 init/check/takeover 三命令
│   ├── types.ts              # 共享类型：InitOptions, CheckOptions, TechStack 等
│   ├── commands/
│   │   ├── init.ts           # init 命令：前置检查 → 交互问答 → 逐级生成文件
│   │   ├── check.ts          # check 命令：11 个检查函数 → 汇总结果
│   │   └── takeover.ts       # takeover 命令：检测技术栈 → 生成草稿配置
│   └── utils/
│       ├── file.ts           # 文件 I/O：safeWrite / appendGitignore / mergeJsonFile
│       ├── template.ts       # 模板系统：resolveTemplatesDir / renderTemplate
│       ├── prompt.ts         # 交互式提示：ask / select（基于 readline）
│       ├── detect.ts         # 技术栈检测：detectTechStack / extractNpmScripts
│       └── logger.ts         # 彩色日志：info / ok / warn / err / checkPass / checkFail
├── templates/                # 项目配置模板（随 npm 包分发）
│   ├── level-0/              # CLAUDE.md.tpl + settings.json.tpl + docs/ 完整结构模板
│   ├── level-1/              # 3 个核心 Skill 模板（plan/review/commit）
│   ├── level-2/              # 5 个 Hook 脚本 + hooks-config.json
│   ├── level-3/              # 14 个 Skill 模板 + mcp.json
│   └── takeover/             # CLAUDE.md.tpl（takeover 专用模板）
├── package.json              # ai-dev-cli@2.1.0，bin: ai-dev-cli
└── tsup.config.ts            # 打包：单入口 CommonJS + shebang

4.2 关键模块说明

入口（index.ts） — 用 commander 注册三个子命令及其选项（--level、--name、--database、--fix、--ci），解析后调用对应的 runInit/runCheck/runTakeover。

init 命令（commands/init.ts） — runInit(options) 先调用 commandExists() 检查前置条件（git/node/claude），然后通过 ask()/select() 收集参数或使用 CLI 传入的选项，最后按级别累加调用 initLevel0~initLevel3。每个 initLevelN 函数使用 loadAndRender() 加载模板、safeWrite() 写入 .claude/skills/{name}/SKILL.md。数据库方案配置存储在 DATABASE_CONFIGS 对象中，每种方案提供 6 个模板变量（TECH_STACK/DB_COMMANDS/DB_ARCHITECTURE/DB_DEPS/DB_BOUNDARY_RULE/CALL_DIRECTION）。

模板系统（utils/template.ts） — resolveTemplatesDir() 从当前文件位置向上遍历查找 templates/ 目录，兼容 src/ 开发模式和 dist/ 发布模式。renderTemplate(content, vars) 用 replaceAll() 替换占位符。模板文件随 npm 包分发，无需用户下载。

文件工具（utils/file.ts） — safeWrite(filepath, content) 检查文件是否存在，已有则跳过并返回 false；safeWriteExecutable() 额外设置 755 权限（Windows 下跳过）；mergeJsonFile() 深度合并对象到已有 JSON 文件（用于追加 hooks 配置）。

5. 使用方式

已发布到 npm（ai-dev-cli），无需下载脚本：

bash

# 在项目根目录运行（交互式）
cd your-project
npx ai-dev-cli init

# 非交互式，直接指定所有参数
npx ai-dev-cli init --level 2 --name myapp --database prisma-sqlite

# 合规审计
npx ai-dev-cli check
npx ai-dev-cli check --fix --ci

# 接管现有项目
npx ai-dev-cli takeover

6. 幂等性保证

safeWrite()（cli/src/utils/file.ts）检查文件是否存在，已有文件不覆盖
appendGitignore() 追加前检查是否已有相同条目
mergeJsonFile() 深度合并 settings.json，已有的 hooks 配置不会被覆盖
可以安全地重复运行，逐步升级级别

7. check 模式实现

runCheck(options)（cli/src/commands/check.ts）依次执行 11 个独立检查函数，汇总 pass/fail/warn 计数：

检查函数	检查内容	--fix 行为
`checkClaudeMd()`	CLAUDE.md 是否存在	提示运行 init
`checkSettingsJson()`	settings.json 格式和 deny 规则	—
`checkHookPermissions()`	Hook 脚本执行权限（755）	`chmod +x`
`checkGitignore()`	敏感文件条目是否在 .gitignore 中	追加条目
`checkEnvSafety()`	.env 是否被 git 追踪	—
`checkLongFiles()`	.ts/.tsx 文件是否超过 300 行	—
`checkAnyType()`	.ts/.tsx 文件中是否存在 any 类型（`: any` / `as any`）	—
`checkDefaultExport()`	.ts/.tsx 文件中是否存在 default export	—
`checkBannedDeps()`	检测禁用依赖（moment/jquery）	—
`checkEnvFilesTracked()`	.env.* 文件是否被 git 追踪	—
`checkFeaturesDoc()`	docs/features.md 存在性、格式、ID 唯一性（WARN 级别）	—

--ci 模式：检查结束后若有 FAIL 项，process.exit(1) 返回非零退出码。

所有检查均为纯 Node.js 实现（fs.existsSync、JSON.parse、fs.statSync 等），不依赖 jq 等外部工具。

8. takeover 模式实现

runTakeover()（cli/src/commands/takeover.ts）分析现有项目并生成草稿配置：

检测阶段（cli/src/utils/detect.ts）：

detectTechStack() — 从 package.json 推断框架（Next.js/Nuxt/React/Vue/Express）、语言（TypeScript/JavaScript）、数据库（Prisma/Mongoose/TypeORM/Drizzle/Sequelize）
extractNpmScripts() — 从 package.json scripts 字段生成命令文档行
detectDirectories() — 扫描常见目录（app/src/components/lib/services 等）
extractDependencies() — 提取所有 dependencies 键名（排序后用于白名单）

输出物：

CLAUDE.md — 从 takeover/CLAUDE.md.tpl 渲染的草稿，包含检测到的技术栈、命令和目录结构
docs/approved-deps.md — 从 package.json 提取的依赖白名单草稿
.claude/settings.json — 基础权限配置

关键原则：所有输出均为草稿，提示用户人工审阅并补充业务上下文。

9. CI 集成

可在 GitHub Actions 中集成 check 模式：

yaml

# .github/workflows/ai-dev-check.yml
name: AI Dev Lifecycle Check
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx ai-dev-cli check --ci

10. 后续扩展

CLI 设计为模块化可扩展结构：

新增命令 — 在 cli/src/commands/ 添加命令模块，index.ts 注册子命令
新增检查项 — 在 cli/src/commands/check.ts 添加检查函数
新增模板 — 在 cli/templates/ 对应级别目录下添加模板文件
扩展技术栈检测 — 在 cli/src/utils/detect.ts 的 detectTechStack() 中添加检测规则

09 - 脚手架设计 ​

1. 定位 ​

2. 三种模式详解 ​

2.1 init 模式 — 建立体系 ​

2.2 check 模式 — 合规审计 ​

2.3 takeover 模式 — 接管现有项目 ​

3. 初始化级别 ​

Level 0 — 最小可用（约 5 分钟） ​

Level 1 — 核心 Skills（在 Level 0 基础上） ​

Level 2 — 质量闸门（在 Level 1 基础上） ​

Level 3 — 完整体系（在 Level 2 基础上） ​

4. CLI 实现架构 ​

4.1 源码目录结构 ​

4.2 关键模块说明 ​

5. 使用方式 ​

6. 幂等性保证 ​

7. check 模式实现 ​

8. takeover 模式实现 ​

9. CI 集成 ​

10. 后续扩展 ​

09 - 脚手架设计

1. 定位

2. 三种模式详解

2.1 init 模式 — 建立体系

2.2 check 模式 — 合规审计

2.3 takeover 模式 — 接管现有项目

3. 初始化级别

Level 0 — 最小可用（约 5 分钟）

Level 1 — 核心 Skills（在 Level 0 基础上）

Level 2 — 质量闸门（在 Level 1 基础上）

Level 3 — 完整体系（在 Level 2 基础上）

4. CLI 实现架构

4.1 源码目录结构

4.2 关键模块说明

5. 使用方式

6. 幂等性保证

7. check 模式实现

8. takeover 模式实现

9. CI 集成

10. 后续扩展