project-setup

项目设置

这是严格的指南。 请严格遵循以下规则。

新项目基于 GitHub 上 loxosceles/project-blueprints 中存储的蓝图创建。

---

工作流

1. 前期检查：验证 devcontainer-state：在进行任何操作之前，检查 ~/.devcontainer-state/.git 是否存在。如果不存在，立即停止并提示：

   ⛔ ~/.devcontainer-state is not a git repo.
   Docker will auto-create mount targets as empty root-owned directories, breaking the devcontainer.
   
   Fix: git clone [email protected]:loxosceles/devcontainer-state.git ~/.devcontainer-state
   
   If ~/.devcontainer-state already exists (empty/root-owned), remove it first:
     sudo rm -rf ~/.devcontainer-state
   

   解决此问题之前，请勿继续。
2. 确定蓝图：询问用户想使用哪种技术栈（例如，“nextjs-sst”、“sst-python”）。从仓库的 blueprints/{stack}.md 读取对应的蓝图。
3. 开始前阅读完整蓝图。理解其中的所有章节。
4. 收集变量：询问 project_name、git_name、git_email 以及蓝图要求的其他值。
5. 按顺序执行各章节：按照蓝图逐步操作。
6. 原样复制片段：fragments/ 中的片段文件是精确配置。复制后，将 {{template_variables}} 替换为实际值。
7. 组装特定技术栈的文件：公共片段（fragments/common/）中包含 {{INJECTION_MARKERS}}。读取 fragments/injections/{stack}/ 中对应的注入片段，并插入标记位置。选择 fragments/dockerfiles/{stack}/ 中的 Dockerfile。每个输出都是一个完整文件，不使用运行时 include 或 source。对于 devcontainer.json，将注入片段中的扩展和设置合并到公共基础配置中。
8. 遇到版本不匹配时暂停：如果某个工具（create-next-app、SST 等）的主版本高于蓝图指定的版本，请停止并询问：“应该评估升级，还是使用固定版本？”
9. 切勿悄悄修改片段：如果片段与当前工具版本不兼容，请报告冲突并询问用户。
10. 运行验证：最后执行所有验证命令。所有命令都必须通过。
11. GitHub Copilot 指令：将 fragments/common/github/copilot-instructions.md 复制到 .github/copilot-instructions.md，并将 fragments/common/github/copilot/review.md 复制到 .github/copilot/review.md。这些文件为 Copilot Chat 和 PR 审查提供代码质量指南。
12. 安装技能：
    • 运行 npx skills add loxosceles/ai-dev --agent claude-code github-copilot codex kiro-cli -y，并询问用户是否需要其他第三方技能。
    • 预先创建所有主机挂载目标（Docker 会以 root 所有者身份创建缺失的源目录，导致权限问题）：

      PROJECT=<project-name>
      mkdir -p ~/.devcontainer-state/cache/${PROJECT}/claude
      mkdir -p ~/.devcontainer-state/cache/${PROJECT}/kiro/settings
      

    • 安装程序始终会将 skills/ 目录创建为便捷符号链接目录，无法阻止这一行为——只需将其加入 gitignore。
    • .gitignore 必须包含：.agents/、.claude/skills/、.kiro/skills/、skills/
    • Steering 文件（从 ~/.devcontainer-state/ai/steering/ 以只读方式挂载到 ~/.kiro/steering/）负责技能自动发现。无需 Agent 配置——技能涵盖所有工作流。
13. 验证 MCP 服务配置：检查 ~/.devcontainer-state/ai/mcp/servers.json 是否存在。如果不存在，提醒用户从 servers.json.template 复制。每次容器启动时，post_start.sh 都会将 MCP 服务分发给所有 Agent（Kiro、Claude、Amazon Q）。
14. 验证 devcontainer 脚本：设置使用两个脚本：
    • post_create.sh —— 容器创建后运行一次（验证、符号链接、Git 身份、技能恢复）
    • post_start.sh —— 每次容器启动时运行（Claude CLI 安装/更新、Claude 设置复制、MCP 服务分发）

规则

• 在当前目录中执行（目录必须为空或为空的 Git 仓库）
• Git 远程仓库必须使用 SSH，绝不能使用 HTTPS：[email protected]:user/repo.git
• 绝不跳过验证步骤
• 如果某个步骤失败，请提供错误信息和可选方案 — 不要默默重试
• 模板变量使用 {{double_braces}} 语法
• 配置以片段文件为准 — 不要自行编造替代方案
• 与 project-migration 保持一致：此技能与 project-migration 对共同涉及的内容（devcontainer、skills、kiro、linting、CI/CD）必须产生相同结果。如果发现此技能的指示与 project-migration 的操作不一致，请停止并在继续之前提醒开发者。

---

渐进式改进

如果开发者纠正了此技能本应避免的行为，请提出对该技能的具体修订建议，以避免今后再次出现同样的问题。