mcpField
S
solo-scaffold

solo-scaffold

github.com/fortunto2开发1848 次安装今天更新
代码仓库

关于 solo-scaffold

根据 PRD 和技术栈模板生成项目骨架的技能，面向需要初始化项目结构、配置和文档的开发者。它还会参考现有项目模式及最新库文档，并可创建 GitHub 私有仓库并推送代码。

主要功能

  1. 01按技术栈生成项目文件结构
  2. 02生成 Makefile 与项目文档
  3. 03参考现有项目及库文档
  4. 04初始化 Git 并推送至 GitHub
  5. 05可选生成 MCP 服务存根

适用场景

  1. 01从 PRD 初始化新项目
  2. 02为不同技术栈创建标准配置
  3. 03根据已有项目模式搭建代码库

MCP 相关

可选用 MCP 工具查询项目信息、代码模式和知识库，并在可用时为生成的项目重新建立代码索引。对于符合条件的 PRD，也可生成 MCP 服务存根。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/fortunto2/solo-factory --skill solo-scaffold

安装后在 Claude Code 中输入/solo-scaffold确认已加载。

附带文件references/stack-structures.md

详细介绍

/scaffold

根据 PRD + 技术栈模板搭建完整项目。创建目录结构、配置文件、CLAUDE.md、Git 仓库，并推送到 GitHub。通过 SoloGraph 研究现有项目以保持模式一致，并使用 Context7 获取最新的库版本。

步骤

  1. 解析参数：从 $ARGUMENTS 中提取 <project-name> 和 <stack-name>。

    • 如果未提供或信息不完整，使用 AskUserQuestion 询问缺失的值。
    • 展示 templates/stacks/*.yaml 中提供的技术栈（以此为准）。 如果 MCP project_info 可用，也展示活跃项目中检测到的技术栈。 列出技术栈名称，以及各 YAML 文件 description 字段中的单行描述。
    • 项目名称应采用 kebab-case。

  2. 加载组织默认值：从 ~/.solo-factory/defaults.yaml 读取：

    • 读取 org_domain（例如 com.mycompany）、apple_dev_team、github_org、projects_dir
    • 如果文件不存在，通过 AskUserQuestion 询问：
      • “你的 Bundle ID 反向域名前缀是什么？”（例如 com.mycompany）
      • “Apple Developer Team ID 是什么？”（可选；如果没有 iOS 项目则留空）
    • 根据答案创建 ~/.solo-factory/defaults.yaml，供以后使用
    • 在所有生成的文件中替换 <org_domain>、<apple_dev_team>、<github_org> 占位符

  3. 加载技术栈 + PRD + 原则：

    • 查找技术栈 YAML：通过 kb_search 或 Glob 在插件模板中搜索 stacks/<stack>.yaml。
    • 如果找不到技术栈 YAML，则使用内置的技术栈知识（软件包、结构、部署）。
    • 检查 PRD 是否存在：docs/prd.md，或在当前目录中搜索 prd.md
      • 如果不存在：生成基础 PRD 模板
    • 查找开发原则：搜索 dev-principles.md 和 dev-principles-my.md（个人扩展），或使用内置的 SOLID/DRY/KISS/TDD 原则。

  4. 通过 SoloGraph 研究现有项目（从自己的代码库中学习——至关重要）：

    生成代码前，研究使用相同技术栈的活跃项目。不要盲目照搬——现有项目可能存在过时模式或错误。评估哪些内容真正有用。

    a. 查找同类项目——使用 project_info() 列出活跃项目，并筛选出技术栈匹配的项目。 例如：对于 ios-swift，查找技术栈匹配的现有项目。

    b. 架构概览——对每个同类项目调用 codegraph_explain(project="<sibling>")。 可获取：目录分层、关键模式（基类、协议、CRUD）、主要依赖项、核心文件。

    c. 搜索可复用模式——使用 project_code_search(query="<pattern>", project="<sibling>")：

    • 搜索特定于技术栈的模式：“MVVM ViewModel”、“SwiftData model”、“AVFoundation recording”
    • 搜索共享基础设施：“Makefile”、“project.yml”、“.swiftlint.yml”
    • 搜索服务：“Service protocol”、“actor service”

    d. 检查共享软件包——调用 codegraph_query("MATCH (p:Project)-[:DEPENDS_ON]->(pkg:Package) WHERE p.name = '<sibling>' RETURN pkg.name")。 收集软件包版本以供参考（但请使用 Context7 验证最新版本）。

    e. 审慎评估要采用还是跳过：

    • **采用：**一致的目录结构、Makefile 目标、配置模式（.swiftlint.yml、project.yml）
    • **采用：**经过验证的基础设施模式（actor 服务、基于协议的 DIP）
    • **过时则跳过：**旧版 API 模式（ObservableObject → @Observable）、已弃用的依赖项
    • **过度复杂则跳过：**不必要的抽象、不适合新项目需求的模式
    • **始终优先：**如果 Context7 的最新最佳实践与旧项目模式冲突，则优先采用前者

    目标：生成的代码应与自己的项目组合保持一致，同时使用当前可用的最佳模式，而非一味沿用旧模式。 将研究范围限制在 2～3 个同类项目，以保持聚焦。

  5. Context7 调研（最新库版本和最佳实践）：

    • 对技术栈中的每个关键软件包：
      • mcp__context7__resolve-library-id — 查找 Context7 库 ID
      • mcp__context7__query-docs — 查询“最新版本、项目设置、推荐的文件结构、最佳实践”
    • 收集：当前版本、推荐的目录结构、配置模式、设置命令
    • 将调研范围限制在最重要的 3-4 个软件包，以保持聚焦

  6. 展示计划并通过 AskUserQuestion 获取确认：

    • 项目路径：<projects_dir>/<name>（取自 defaults.yaml 或当前目录）
    • 技术栈名称，以及从 Context7 获取的关键软件包及其版本
    • 拟定的目录结构
    • 创建文件前请用户确认或调整

  7. 创建项目目录：

    mkdir -p <projects_dir>/<name>

  8. 根据技术栈创建文件结构。 SGR 优先：始终先创建领域 schema/model，再编写任何逻辑或视图。 每个项目都包含以下通用文件：

    <projects_dir>/<name>/
├── CLAUDE.md          # AI-friendly project docs (map, not manual — see Harness Engineering)
├── Makefile           # Common commands (run, test, build, lint, deploy, integration)
├── README.md          # Human-friendly project docs
├── docs/
│   ├── prd.md         # Copy of PRD
│   ├── QUALITY_SCORE.md  # Domain quality grades (harness: garbage collection)
│   └── ARCHITECTURE.md   # Module boundaries and dependency rules
├── cli/               # CLI utility — mirrors core business logic (CLI-First Testing principle)
│   └── main.ts|py     # Deterministic pipeline entry point (no LLM required)
├── .claude/
│   └── skills/        # Product-specific workflow skills
│       └── dev/
│           └── SKILL.md  # Dev workflow skill (run, test, deploy)
└── .gitignore         # Stack-specific ignores

    **CLI 优先测试：**生成一个 cli/ 目录，其中包含一个从 lib/（或同等目录）导入核心业务逻辑的存根。CLI 应能以确定性的方式运行主流程，且不依赖 LLM、网络或 UI。这样便可使用 make integration 验证流程。请参阅 dev-principles.md → “CLI-First Testing”。

    .claude/skills/dev/SKILL.md — 产品开发工作流技能

    生成一个技能，指导 Claude 如何处理此特定项目。结构如下：

    ---
name: <name>-dev
description: Dev workflow for <Name> — run, test, build, deploy. Use when working on <Name> features, fixing bugs, or deploying changes. Do NOT use for other projects.
license: MIT
metadata:
  author: <github_org>
  version: "1.0.0"
allowed-tools: Read, Grep, Glob, Bash, Write, Edit
---

    正文应包括：

    • **技术栈：**关键软件包、版本、配置文件所在位置
    • 命令：make dev、make test、make build、make deploy（来自 Makefile）
    • **架构：**目录结构、命名约定、关键模式
    • **测试：**如何运行测试、测试文件所在位置、测试约定
    • **常见任务：**添加新页面/屏幕、添加 API 端点、添加 model

    这样，每个脚手架生成的项目都能立即适配 Claude——新会话可通过该技能获取项目上下文。

    MCP 服务（可选）：如果 PRD 表明这是数据、AI 或开发者产品，也生成 MCP 服务存根。 完整的“MCP + Skills bundle”模式以及生成 MCP 的规则，请参阅 templates/mcp-skills-bundle.md。

    然后添加特定于技术栈的文件。各技术栈的文件清单请参阅 references/stack-structures.md（8 种技术栈：nextjs、ios、kotlin、cloudflare、astro-static、astro-hybrid、python-api、python-ml）。

  9. 生成 Makefile — 根据技术栈调整，包含以下目标：help、dev、test、lint、format、build、clean、deploy。

    • 如果项目有 CLI 或确定性流程，则添加 integration 目标（若尚未实现，则添加带注释的存根）
    • ios-swift 还必须包含：generate（xcodegen）、archive（xcodebuild archive）、open（打开 .xcarchive 以进行分发）
    • Makefile 是标准命令接口——/build 和 /review 使用 make 目标，而不是原始命令

  10. 生成 CLAUDE.md，为新项目生成约 100 行内容（作为地图，而非手册）：

  • 项目概述（来自 PRD 的问题／解决方案）
  • 技术栈（来自 Context7 的软件包及版本）
  • Agent 行为默认设置（Karpathy 原则）：
    • 编码前先思考：说明假设，遇到困惑时提问
    • 简洁优先：只写必要的代码，不做推测性抽象
    • 精准修改：只改必要之处，遵循现有风格
    • 目标导向：将指令转化为可验证的成功标准
  • **技能部分：**列出可用的 .claude/skills/ 并附上说明
  • 目录结构
  • 常用命令（参考 make help）
  • 质量关卡（完成任何任务前）：
    1. “我是不是在做无用功？”——重新阅读请求
    2. “这段代码是不是很糟糕？”——资深工程师会认可吗？
    3. “怎样才能做到出色？”——大家都忽略了什么关键见解？
  • 架构原则（参考 dev-principles，不要内联）
  • 不要做的事部分（项目特定的负面约束）
  • 偏离部分（反模式：排期而非执行、列点而非编写代码）
  • MCP 集成部分（可选，如果有可用的 MCP 工具）： 列出可用的 MCP 工具：project_code_search、kb_search、session_search、codegraph_query、project_info、web_search

  1. 生成 README.md——包含项目名称、描述、前提条件、设置、运行／测试／部署说明。

  2. 生成 .gitignore——添加特定于技术栈的匹配模式。

  3. **将 PRD 复制到 docs/：**从知识库复制，或直接在此处生成。

  4. 初始化 Git 并创建首次提交：

    cd <projects_dir>/<name>
git init && git add . && git commit -m "Initial project scaffold

Stack: <stack-name>
Generated by /scaffold"

  5. 创建 GitHub 私有仓库并推送：

    cd <projects_dir>/<name>
gh repo create <name> --private --source=. --push

  6. 注册项目并索引代码（可选，如果有可用的 MCP 工具）：

    • 如果有可用的 project_code_reindex MCP 工具，则为新项目建立代码索引，以便进行代码搜索： 
      mcp__solograph__project_code_reindex(project="<name>")

  7. 输出摘要：

    项目脚手架已生成！

  路径：   <projects_dir>/<name>
  GitHub： https://github.com/<user>/<name>
  技术栈： <stack-name>
  PRD：    docs/prd.md
  CLAUDE： 已配置
  技能：   .claude/skills/dev/（项目工作流）

后续步骤：
  cd <projects_dir>/<name>
  <install command>    # pnpm install / uv sync / 等
  <run command>        # pnpm dev / uv run ... / 等

然后：/setup → /plan "First feature" → /build

验证

在报告“项目脚手架已生成”之前：

  1. 验证所有生成的文件都存在（列出目录树）。
  2. 运行安装命令（pnpm install、uv sync 等）——必须成功。
  3. 如果适用，运行开发／构建命令——不得报错。
  4. 验证Git 初始化和首次提交成功（git log --oneline -1）。
  5. 验证GitHub 仓库已创建（gh repo view 或检查 URL）。

运行安装命令并确认成功之前，绝不要声称“脚手架已完成”。

常见问题

未找到 Stack YAML

原因：templates/stacks/ 中缺少 Stack 模板，或模板未创建符号链接。 **解决方法：**如果未找到模板，技能会使用内置知识。要解决此问题，请确保 solo-factory/templates/stacks/<stack>.yaml 存在。

创建 GitHub 仓库失败

原因：gh CLI 未通过身份验证，或仓库名称已被占用。 **解决方法：**先运行 gh auth login。如果名称已被占用，请换一个项目名称。

Context7 查询失败

**原因：**MCP 服务未运行，或 Context7 遭遇速率限制。 **解决方法：**技能会回退使用 Stack YAML 中的版本。Context7 可以增强效果，但不是必需的。

缺少 org 默认值

**原因：**尚未创建 ~/.solo-factory/defaults.yaml。 **解决方法：**先运行 /init 完成一次性设置；或者，技能会以交互方式询问 bundle ID 和 team ID。

评论

支持 Markdown