project-bootstrapper

Project Bootstrapper

理念：在编写任何代码之前，先定义代码必须遵循的规范。漏洞应在设计阶段就得到预防，而不是等到运行时才被发现。

这是一个元技能——它不会编写应用代码。它会生成规则、模式、护栏和质量标准，用于约束之后由任何开发者或 AI 助手编写的所有代码。

工作原理

[Idea] → [Interview] → [Tech Stack] → [Skill Map] → [Generate Skills] → [Validate] → [Code]

激活条件

此技能会在以下情况下激活：

• 用户描述一个新的软件项目构想
• 用户说“bootstrap”“new project”“start from scratch”“set up project”
• 用户想为现有代码库生成一套技能
• 用户要求制定编码标准、项目脚手架或开发护栏
• 在任何应该于开发开始前创建技能的情境中

重要：先阅读参考资料

生成任何技能之前，必须按顺序阅读以下参考文件：

1. references/skill-catalog.md — 包含 40 多个技能领域的完整目录
2. references/skill-template.md — 每项技能都必须遵循的通用模板
3. references/generation-guide.md — 包含代码的领域专属生成指南
4. references/quality-standards.md — 生成技能的质量检查清单
5. references/cross-cutting-concerns.md — 适用于所有技能的规则

---

阶段 1：项目信息收集

1.1 — 了解构想

提取或询问以下信息：

是什么（产品）：

• 这个项目能做什么？（一句话）
• 属于什么类型？（Web 应用、移动应用、桌面应用、CLI、库/SDK、API 服务、浏览器扩展、IoT、嵌入式应用、游戏、数据流水线、机器学习平台、包含多个产品的单体仓库）
• 最终用户是谁？（开发者、消费者、企业、内部团队）
• 盈利模式是什么？（开源、免费增值、SaaS 订阅、一次性购买、市场平台、广告支持、企业许可）

规模（体量）：

• 上线时预计有多少用户？12 个月后呢？
• 数据量有多大？（记录、文件、每秒事件数、存储空间）
• 覆盖的地理范围是什么？（单一区域、洲际、全球）
• 可用性要求是什么？（99.9%、99.95%、99.99%）

如何实现（约束条件）：

• 必须使用哪些技术？（必须使用 React、必须部署在 AWS 上等）
• 是否已有代码库？（从零开始还是基于现有项目）
• 团队规模多大？（个人、小型团队 2-5 人、中型团队 5-15 人、大型团队 15 人以上）
• 时间安排如何？（黑客松/周末、数周内交付 MVP、数月内投入生产）
• 预算限制是什么？（仅限免费套餐、适中、企业级）
• 有哪些合规要求？（GDPR、HIPAA、SOC2、PCI-DSS、COPPA、CCPA）

如果用户已经提供了详细信息，请从其消息中提取答案，而不是再次询问。只询问缺失且确实需要用于确定技术栈的信息。

1.2 — 确定技术栈

根据答案，推荐一套完整的技术栈。

🔍 强制要求：版本调研（最新稳定版）——零容忍

这是不可协商的。在提出任何技术方案之前，你必须通过实时查询验证其最新稳定版本。

⚠️ 重要：AI 模型的知识存在截止时间。软件包生态每天都在变化。使用过时版本生成的技能会产出易受攻击、已弃用的代码。

调研流程（针对每项技术执行）：

1. 使用可用工具（按优先顺序）：

   • WebSearch："{package} latest stable version {current_year}"
   • WebFetch：官方网站（例如 nextjs.org、python.org、go.dev）
   • Context7：resolve-library-id → query-docs 查询更新日志
   • 软件包注册表：npmjs.com、pypi.org、crates.io、pkg.go.dev、maven.apache.org

2. 提取准确版本号：

   • 格式：Major.Minor.Patch（例如 Next.js 16.1.0）
   • 确认版本为稳定版（不是 alpha、beta、RC、canary、nightly）
   • 记录发布日期——若超过 6 个月未更新，则不予采用

3. 记录验证结果：

   Technology: Next.js
   Version: 16.1.0
   Verified via: nextjs.org/blog
   Verification date: 2026-03-09
   Release date: 2026-02-15
   Node requirement: >= 22.0.0
   

严格规则：

• ✅ 必须：验证每项依赖，而不仅仅是框架
• ✅ 必须：在所有配置文件（package.json、requirements.txt、Cargo.toml 等）中锁定准确版本
• ✅ 必须：所有代码示例均使用已验证版本中的最新 API／语法
• ❌ 绝不：在任何情况下使用记忆中的版本
• ❌ 绝不：跳过验证，即使是“知名”软件包也不例外
• ❌ 绝不：使用旧版本中已弃用的 API
• ⚠️ 警告：如果验证失败，请明确标注：⚠️ VERSION UNVERIFIED — MUST CONFIRM

项目弃用检测：

• 距上次提交／发布超过 12 个月 = 调研替代方案
• 超过 6 个月未收到维护者对问题的回复 = 危险信号
• 安全公告发布超过 30 天仍未修复 = 切勿使用

调研查询示例：

• "next.js latest version" → nextjs.org 或 npm
• "postgresql latest stable release" → postgresql.org
• "tailwind css latest version" → tailwindcss.com 或 npm
• Context7：解析库 ID → 查询文档中的版本／更新日志

技术栈决策表

按分层决策表进行组织：

┌──────────────────────────────────────────────────────────────────────┐
│  TECH STACK PROPOSAL (versions verified: {date})                     │
├────────────────┬─────────────────────────────────┬───────────────────┤
│ Category       │ Choice                          │ Rationale         │
├────────────────┼─────────────────────────────────┼───────────────────┤
│ Language       │ {name} {verified latest version} │                   │
│ Runtime        │ {name} {verified latest version} │                   │
│ Framework      │ {name} {verified latest version} │                   │
│ Database       │ {name} {verified latest version} │                   │
│ ORM/Query      │ {name} {verified latest version} │                   │
│ Cache          │ {name} {verified latest version} │                   │
│ Auth           │ {name} {verified latest version} │                   │
│ UI Library     │ {name} {verified latest version} │                   │
│ CSS/Styling    │ {name} {verified latest version} │                   │
│ State Mgmt     │ {name} {verified latest version} │                   │
│ API Style      │ {name} {verified latest version} │                   │
│ Validation     │ {name} {verified latest version} │                   │
│ Testing        │ {name} {verified latest version} │                   │
│ CI/CD          │ {name} {verified latest version} │                   │
│ Hosting        │ {name}                           │                   │
│ Monitoring     │ {name} {verified latest version} │                   │
│ Email          │ {name} {verified latest version} │                   │
│ File Storage   │ {name}                           │                   │
│ Search         │ {name} {verified latest version} │                   │
│ Queue/Jobs     │ {name} {verified latest version} │                   │
│ Analytics      │ {name} {verified latest version} │                   │
└────────────────┴─────────────────────────────────┴───────────────────┘

仅包含与项目相关的行。每项选择均需附上一句理由。

请等待用户确认后再继续。 技术栈决定后续的一切。

跨语言版本验证矩阵

针对每种语言，验证以下工具的版本：

┌─────────────────────────────────────────────────────────────────────────┐
│ LANGUAGE     │ CORE VERSION │ PACKAGE MANAGER │ LINTER     │ TESTER      │
├─────────────────────────────────────────────────────────────────────────┤
│ TypeScript   │ Latest Node  │ npm/pnpm 10+    │ ESLint 9+  │ Vitest 3+   │
│ Python       │ 3.12+        │ pip/uv          │ Ruff 0.9+  │ pytest 8+   │
│ Go           │ 1.24+        │ go modules      │ golangci   │ go test     │
│ Rust         │ Latest       │ cargo           │ clippy     │ cargo test  │
│ Java         │ 21 LTS       │ Maven/Gradle    │ checkstyle │ JUnit 5     │
│ Kotlin       │ 2.1+         │ Gradle          │ ktlint     │ Kotest      │
│ C#           │ .NET 9+      │ NuGet           │ analyzers  │ xUnit       │
│ Swift        │ 6.0+         │ SwiftPM         │ swiftlint  │ XCTest      │
│ PHP          │ 8.4+         │ Composer 2+     │ PHPStan 2+ │ PHPUnit 11+ │
│ Ruby         │ 3.4+         │ Bundler         │ RuboCop    │ RSpec       │
└─────────────────────────────────────────────────────────────────────────┘

多语言项目：为每种语言分别生成 {language}-standards 技能。

1.3 — 生成技能图谱

根据已确认的技术栈，生成技能图谱——需要生成的完整技能列表。阅读 references/skill-catalog.md，了解完整的领域目录。

必备技能（为每个项目生成）：

1. project-architecture — 文件夹结构、模块边界、命名
2. {language}-standards — 语言级编码规则
3. security-hardening — 深度防御、输入/输出、机密信息、依赖项
4. error-handling — 错误层级、传播、恢复
5. data-validation — 架构验证、净化、边界
6. testing-strategy — 测试类型、覆盖率、模拟、固定装置
7. performance-optimization — 预算、性能分析、缓存、延迟加载
8. git-workflow — 分支、提交、PR、发布
9. documentation-standards — 代码文档、API 文档、README、ADR
10. privacy-compliance — PII 处理、数据生命周期、同意、GDPR/CCPA
11. dependency-management — 版本管理、审计、更新策略、锁文件

条件性技能（项目需要时生成）：

• {framework}-patterns — 框架特定约定
• database-design — 架构、迁移、索引、查询
• api-design — 端点、版本管理、分页、速率限制
• ui-engineering — 组件、样式、响应式、无障碍
• state-management — 客户端/服务端/URL/表单状态模式
• auth-patterns — 身份验证、授权、会话、令牌、MFA
• devops-pipeline — CI/CD、环境、部署、回滚
• observability — 日志、指标、跟踪、告警
• accessibility-standards — WCAG 合规、ARIA、键盘导航
• internationalization — i18n、l10n、RTL、复数形式
• payment-integration — 计费、订阅、webhook、PCI
• file-handling — 上传、存储、处理、CDN
• realtime-system — WebSocket、SSE、发布/订阅、在线状态
• email-system — 事务邮件、模板、队列、合规
• search-implementation — 引擎、索引、相关性、自动补全
• background-jobs — 队列、调度、重试、死信
• mobile-patterns — 导航、离线、推送、深层链接
• desktop-patterns — 窗口管理、托盘、IPC、自动更新
• cli-design — 命令、参数、输出、配置、Shell 补全
• monorepo-management — 工作区、边界、版本管理
• ai-integration — 大模型调用、提示词、流式传输、成本、安全性
• caching-strategy — 层级、失效、CDN、stale-while-revalidate
• rate-limiting — 算法、层级、标头、分布式限流
• feature-flags — 发布、定向、紧急关闭开关、清理
• migration-strategy — 零停机、数据迁移、向后兼容
• container-orchestration — Docker、K8s、健康检查、资源
• infrastructure-as-code — Terraform/Pulumi、状态、模块
• event-driven-architecture — 事件溯源、CQRS、Saga
• graphql-patterns — 架构设计、解析器、N+1、批处理
• websocket-patterns — 连接管理、房间、重新连接
• microservice-patterns — 服务边界、通信、服务发现

按生成层组织并呈现技能图谱。等待用户确认。

---

Phase 2：技能生成引擎

2.1 — 生成顺序（依赖层）

严格按照依赖顺序生成技能——后续技能可以引用之前的技能：

Layer 0: project-architecture
         (defines folder structure, module boundaries, naming — everything else references this)

Layer 1: {language}-standards, git-workflow, documentation-standards
         (foundational coding and process standards)

Layer 2: security-hardening, error-handling, data-validation, privacy-compliance,
         dependency-management
         (cross-cutting safety and quality concerns)

Layer 3: database-design, api-design, auth-patterns, caching-strategy
         (data and communication layer)

Layer 4: {framework}-patterns, ui-engineering, state-management,
         accessibility-standards
         (presentation and interaction layer)

Layer 5: testing-strategy, performance-optimization
         (quality assurance — needs all other skills to exist first)

Layer 6: devops-pipeline, observability, container-orchestration,
         infrastructure-as-code
         (operations layer)

Layer 7: Domain-specific skills (payments, i18n, email, search, realtime,
         background-jobs, feature-flags, AI, etc.)
         (only relevant domains)

2.2 — 技能文件结构

每个生成的技能都必须包含以下文件树：

{skill-name}/
├── SKILL.md              # Main instructions (< 500 lines)
├── references/
│   ├── patterns.md       # Approved patterns with full code examples
│   ├── anti-patterns.md  # Forbidden patterns with severity + explanation
│   └── checklist.md      # Pre-commit/pre-merge verification checklist
└── templates/            # (optional) Code templates, configs
    └── *.template.*

2.3 — 内容要求

阅读 references/skill-template.md，了解准确的骨架。阅读 references/generation-guide.md，了解特定领域的内容要求。

每个生成的技能 MUST 包含：

1. YAML frontmatter — name + 积极明确的 description，以确保可靠触发
2. 激活条件 — 明确的触发条件（文件类型、目录、用户短语）
3. 项目上下文 — 引用实际的项目技术、路径和决策
4. 带编号的核心规则（每个技能 15-40 条）— 每条都附带理由和代码示例
5. 获批模式 — 可复制粘贴的代码，展示正确做法
6. 反模式及严重程度（🔴 严重 / 🟠 高 / 🟡 中 / 🟢 低）
7. 性能预算 — 具体、可衡量的数字，而非含糊的目标
8. 安全检查清单 — 特定领域的安全验证项
9. 错误场景表 — 失败情况、检测方式和恢复方法
10. 边缘情况 — 记录并附上处理说明
11. 集成点 — 说明此技能如何与其他生成的技能衔接
12. 提交前检查清单 — 代码提交前的验证项

2.4 — 编写原则

• 解释 WHY：Claude 和开发者都很聪明——推理胜过死板命令
• 具体胜于抽象：真实代码示例胜过代码描述
• 特定于项目：引用实际的技术选型、路径和决策，绝不泛泛而谈
• 明确主张：选定一种最佳做法并贯彻执行，不要提供多个选项
• 可测试：每条规则都必须可验证（lint 规则、测试或代码审查项）
• 示例可编译：所有代码示例都必须可正常运行，确保复制粘贴即可使用，不得使用伪代码
• 正反兼顾：每条关键规则都要展示正确和错误的做法

2.5 — 技能间一致性

生成所有技能后，验证以下内容：

• 各技能之间没有矛盾
• 所有技能中的共享术语保持一致
• 导入路径指向实际项目结构
• 所有技能中的技术版本一致
• 错误处理模式统一
• 日志格式处处一致
• 验证方法处处一致
• 安全规则没有冲突

---

第 3 阶段：输出

3.1 — 目录布局

{project-root}/
├── .claude/
│   └── skills/
│       ├── project-architecture/
│       │   ├── SKILL.md
│       │   └── references/
│       ├── {language}-standards/
│       │   ├── SKILL.md
│       │   ├── references/
│       │   └── templates/
│       ├── security-hardening/
│       │   ├── SKILL.md
│       │   └── references/
│       ├── ... (all generated skills)
│       └── _bootstrap-manifest.json
├── .gitignore
└── ... (application code comes AFTER bootstrap)

3.2 — 引导清单

生成 _bootstrap-manifest.json：

{
  "project": "{name}",
  "bootstrapped_at": "{ISO-8601}",
  "tech_stack": {},
  "skills_generated": [
    {
      "name": "{skill-name}",
      "path": ".claude/skills/{skill-name}/",
      "layer": 0,
      "depends_on": [],
      "domains_covered": ["architecture", "folder-structure", "naming"]
    }
  ],
  "total_skills": 0,
  "total_rules": 0,
  "total_anti_patterns": 0,
  "coverage": {
    "security": true,
    "performance": true,
    "privacy": true,
    "testing": true,
    "accessibility": true,
    "error_handling": true,
    "documentation": true,
    "observability": true
  }
}

---

第 4 阶段：验证

在宣布引导完成之前，使用 JavaScript 和 Python 验证器执行验证：

验证清单

1. 完整性 — 至少有一个技能覆盖每个技术栈组件
2. 矛盾 — 任意两个技能都没有相互冲突的建议
3. 依赖项 — 每个技能的 depends_on 指向的目标都存在
4. 覆盖范围 — 安全、性能、隐私、测试和错误处理均已覆盖
5. 具体性 — 技能引用实际的项目名称、路径和版本
6. 质量 — 对生成的技能运行验证器

运行验证器

JavaScript/Node.js（默认）：

# Validate all skills
node scripts/validate_bootstrap.js .claude/skills/

# Check version consistency
node scripts/version_checker.js .claude/skills/

# Check compliance (if you have source code)
node scripts/check_skill_compliance.js src/

Python（替代方案）：

# Validate all skills
python scripts/validate_bootstrap.py .claude/skills/

# Check version consistency
python scripts/version_checker.py .claude/skills/

# Check compliance
python scripts/check_skill_compliance.py src/

验证输出

呈现摘要表：

╔═══════════════════════════════════════════════════╗
║  BOOTSTRAP COMPLETE                               ║
╠═══════════════════════════════════════════════════╣
║  Project: {name}                                  ║
║  Skills Generated: {N}                            ║
║  Total Rules: {N}                                 ║
║  Total Anti-Patterns: {N}                         ║
║  Security Rules: {N}                              ║
║  Performance Budgets: {N}                         ║
║  Privacy Controls: {N}                            ║
║  Test Requirements: {N}                           ║
╠═══════════════════════════════════════════════════╣
║  ✅ No contradictions found                       ║
║  ✅ All dependencies resolved                     ║
║  ✅ Full coverage verified                        ║
║  ✅ Validators passed                             ║
║  ✅ Ready to code                                 ║
╚═══════════════════════════════════════════════════╝

---

第 5 阶段：持续合规（project-manager 技能）

严重： 引导完成后，project-manager 技能将确保持续合规：

project-manager 的职责

• 监控所有代码变更，实时跟进
• 验证每项修改是否符合当前启用的技能
• 阻止存在技能违规的提交
• 每周报告合规指标
• 引导开发者回归技能要求
• 自动检测技能偏移

可用工具

JavaScript：

# Check code compliance
node scripts/check_skill_compliance.js src/

# Analyze skill coverage
node scripts/analyze_skill_coverage.js src/

# Generate weekly report
node scripts/generate_compliance_report.js --week

Python：

# Check code compliance
python scripts/check_skill_compliance.py src/

# Analyze skill coverage
python scripts/analyze_skill_coverage.py src/

# Generate weekly report
python scripts/generate_compliance_report.py --week

提交前钩子

设置自动合规检查：

# Install pre-commit hook
cp scripts/pre-commit.example .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

结果： 技能将成为主动防护栏，而不只是文档。

---

阶段 6：交接

完成引导和验证后：

1. 确认所有技能均已在 .claude/skills/ 中生成
2. 说明project-manager 技能将负责监控合规情况
3. 展示如何运行验证器（JS 和 Python 两种选项）
4. 演示合规性检查命令
5. 过渡到实际开发

创建或编辑的每个文件都会自动受相关技能约束，并由 project-manager 技能强制执行。

---

此技能的规则

核心原则

• 此技能生成其他技能，不会生成应用程序代码
• 生成的技能必须针对具体项目，而非通用样板
• 如有疑问，宁可多生成技能，也不要少生成
• 如果用户的项目需要目录中没有的领域，请为其创建新技能
• 遵循用户的语言偏好（默认为英语）
• 技术栈与技术无关：适用于 TypeScript、Python、Go、Rust、Java、C#、Swift、Kotlin、PHP、Ruby，或任意组合
• 对于多语言项目，按语言生成技能
• 生成任何技能之前，先阅读所有参考文件

验证要求

生成后始终运行验证器：

# Option 1: JavaScript/Node.js (recommended, no Python needed)
node scripts/validate_bootstrap.js .claude/skills/

# Option 2: Python (if available)
python scripts/validate_bootstrap.py .claude/skills/

宣布引导完成之前，验证必须通过。

必需技能

**始终与其他技能一同生成 project-manager 技能。**它将：

• 在整个开发过程中监控合规情况
• 实时根据技能验证代码
• 生成合规报告
• 防止技能偏离

版本核验

**重要：**必须通过实时查询核验每项技术的版本：

• 使用 WebSearch、WebFetch 或 Context7
• 记录核验来源和日期
• 切勿使用记忆中的版本信息
• 核验所有依赖项，而不只是框架

生成后检查清单

交接前：

• 已在 .claude/skills/ 中生成所有技能
• 已包含 project-manager 技能
• 验证已通过（JS 或 Python）
• 已运行版本检查器
• 已创建 _bootstrap-manifest.json
• 已向用户说明合规工具
• 已提及 pre-commit hooks