byerlikaya/claude-starter-kit

## 为什么选择这个套件？ 大多数“Agent 设置”只是一堆建议——规则静躺在文件里，是否被遵守全凭模型自觉。这个套件不同：它将一支**纪律严明的工程团队**空降到 Claude Code 中，在这里，**真正重要的规则是门，而不是提醒**——它不仅告诉 Agent 规则，还让破坏关键规则变得不可能，并且能安全地安装到你现有的 repo 中。 | | | |---|---| | 👥 | **是一个团队，而不是一个 prompt** — 11 个专家 Agent 在 计划 → 构建 → 审计 → 发布 全流程自动串联；你无需手动连接，主线程会完成这一切。 | | 🛡️ | **安全与隐私是强制门，而非可选项** — 涉及高风险的变更必须通过安全/隐私审计才能关闭。 | | 🚦 | **每次提交都需你亲自批准** — 没有你的明确同意，任何 `commit`/`push` 都不会执行，即使是在 auto/bypass 模式下，这也是在工具层面强制执行的。 | | 🌿 | **对现有 repo 绝对安全** — `adopt` 会在专门的分支上交接套件；绝不会触碰 `main` 分支，你可以在保留前进行审查。 | ## 🧠 Agents — 套件的核心 **11 个 Agents**，每一个都是一个**轻量触发器** — 它只说明*是谁*以及*何时启动*，并将*如何执行*委托给 skill。主线程会跨**五个阶段**选择并串联它们，在任何代码提交之前提升质量： | Agent | 阶段 | 触发时机 | 模型 | |:--|:--|:--|:--:| | **planner-csk** | 🧭 理解 | 范围不明确时 | `inherit` | | **backend-expert-csk** | 🔨 生产 | server / API / 业务逻辑 | `inherit` | | **database-expert-csk** | 🔨 生产 | schema、migration、index、cache | `inherit` | | **frontend-expert-csk** | 🔨 生产 | UI、组件、客户端工作 | `inherit` | | **devops-expert-csk** | 🔨 生产 | 部署、CI pipeline、事故 | `inherit` | | **security-expert-csk** | 🔍 审计 | 认证 / IDOR / 注入 / 密钥 · **若是安全关键型则强制执行** | `sonnet` | | **privacy-agent-csk** | 🔍 审计 | 个人数据 (KVKK / GDPR) | `sonnet` | | **test-expert-csk** | 🔍 审计 | 测试、覆盖率、回归 | `inherit` | | **review-agent-csk** | ✅ 关闭 | 提交前的代码健康审查 | `haiku` | | **commit-agent-csk** | ✅ 关闭 | 提出提交建议，等待批准 | `haiku` | | **session-manager-csk** | 🤝 交接 | 上下文占满 / 阶段边界 | `haiku` | ## 三大原则 1. **Agent = 轻量触发器。** Agent 只声明“是谁、何时启动”；它保持简短，将“如何执行”留给 skill。 2. **Skill = 单一事实来源。** 实际的方法和规则存在于 skill 中；它们不会被复制到 Agent 里。 3. **Rule → gate（规则即门禁）。** 真正重要的规则在工具层面（hook · permission · eval）强制执行。无需指望模型去记住它。 ## 本套件的不同之处 大多数针对 Claude Code 的“Agent 设置”分为两类：一个是包含规则的**大型 prompt 文件**，或者是需要你自己组装的 **agents/skills 集合**。两者都将最困难的部分——*真正落实纪律*——寄托于模型的自律。本套件则不然。 | 关键要素 | 典型的 Agent 套件 / prompt 集合 | Claude Starter Kit | |---|---|---| | **关键规则** | 存在于 `.md` 文件中；只有模型想起来时才会遵守 | **作为 gate 在工具层面强制执行** — git hook (`trace-scan`)、`settings.json` 权限配置、`guard-bash.sh` PreToolUse。打破它们是*不可能的*，而不是*不提倡的* | | **结构** | 单个开发 prompt，或者由你自己编排的松散 Agent 列表 | **一支由 11 个专家 Agent 组成的团队**，跨 5 个阶段（理解 → 生产 → 审计 → 关闭 → 交接）自动串联 — 由主线程负责串联它们，而不是你 | | **安全与隐私** | 可选的建议，很容易被跳过 | **强制的审计 gate** — 涉及高风险的变更在通过安全/隐私审查之前无法关闭 | | **提交** | 模型可能会自行提交 | **每次提交都需要你的批准** — 即使在 auto/bypass 模式下，也是在工具层面强制执行 | | **接入现有 repo** | 假设“从零开始”；需手动移植 | **`adopt` 在分支上交接套件** — 绝不触碰 `main`；你在保留前会进行审查 | | **“具体做法”存放位置** | 规则和方法被复制到每个 Agent prompt 中 → 导致偏移和重复 | **Agent = 轻量触发器**（是谁/何时启动）；方法作为**单一事实来源**仅存放在一个 **skill** 中，并被 30 个 skills 复用 | **一句话总结：** 类似的项目只是交给你*一堆建议*；而这个套件将一支*纪律严明的工程团队*空降到 Claude Code 中 — 在这里，真正重要的规则是**门，而不是提醒**。 ## 安装与运行 **两个入口：** `start.sh` 用于搭建**全新**项目；**`adopt`** (`adopt.sh`) 用于将套件交接给**现有**项目。选择任何渠道 — 每个渠道运行的命令完全一样。 **npx** — 无需安装任何内容： ``` npx @byerlikaya/claude-starter-kit # fresh project npx @byerlikaya/claude-starter-kit adopt # existing project npx @byerlikaya/claude-starter-kit@latest update # refresh a project that already has the kit ``` **Homebrew:** ``` brew install byerlikaya/tap/claude-starter-kit claude-starter-kit # fresh project claude-starter-kit adopt # existing project brew upgrade byerlikaya/tap/claude-starter-kit && claude-starter-kit update # refresh a project that already has the kit ``` **Release tarball** — 无需包管理器： ``` gh release download --repo byerlikaya/claude-starter-kit -p '*.tgz' && tar xzf claude-starter-kit-*.tgz bash start.sh # fresh project bash adopt.sh # existing project — re-run it to refresh a project that already has the kit (update) ``` ### 🌱 全新项目 — `start.sh` ``` bash start.sh [--backend|--frontend|--mobile|--fullstack] [--dotnet|--generic] [-h] ``` 这是一个安装向导。在没有 flag 的情况下，它会引导你完成每一个步骤（profile → backend stack → 摘要与批准）；这些 flag 用于静默/CI 环境，`-h` / `--help` 可打印用法。每一个选项在**正式安装前**都会展示即将安装的具体内容。 | Profile | 专家 Agents | 核心高亮 skills | |---|---|---| | `--backend` | backend · database | db-migration · api-design · observability | | `--frontend` | frontend | frontend · a11y · i18n-integrity | | `--mobile` | frontend (+ React Native/Expo layer) | frontend-rn-expo · a11y | | `--fullstack` | 包含所有 | 所有 skills — backend **以及** web **以及** mobile (RN/Expo) | 没有单独的移动端 Agent：`frontend-expert-csk` 涵盖了 Web、移动端和桌面端，而移动端的*具体做法*存放在 `frontend-rn-expo` skill 中。`--fullstack` 也会安装该 skill，因此全栈项目无需额外选择 `--mobile` 即可直接支持移动端。 仅在选择了 `--backend`/`--fullstack` 时才会询问后端技术栈：**`--dotnet`** 会在批准门后引入 .NET / DevArchitecture 架构模式（MediatR CQRS · IResult · AOP）；**`--generic`** 则在不包含该模式的情况下安装相同的专家支持 — 适用于 Node、Go、Python，或采用不同模式的 .NET 项目。 ### 🔄 现有项目 — `adopt.sh` ``` bash adopt.sh # at the root of the target project ``` 将套件应用于一个正在进行的项目中，就像**一个团队将项目移交给另一个团队**一样 — 项目不会被破坏，已经做出的决策不会丢失，而且套件也不会一直被动等待。 所有更改都会落在单独的 git 分支上，且**处于 staged（暂存）状态但未提交** — 因此每一个新增和更改的文件都会显示在编辑器的 Source Control / Changes（源代码管理 / 更改）面板中；你可以在那里进行审查，然后通过 `git commit` 接受（或者使用 reset 丢弃）。`main` 分支保持原样，不受影响。套件的 Agents 会并列安装（绝不发生冲突），纪律层通过单个 `@import` 绑定，`settings.json` 会以感知 schema 的方式合并，并且现有的 husky/lefthook 链会通过 shim 与套件并行运行。最后它会生成一个持久化的 `docs/HANDOVER.md` 和一份 ADR 作为结尾，确保决策被记录在版本控制中，而不是流失在闲聊里。 ### 🔁 更新已安装的项目 在项目根目录下运行 — 所有渠道使用的命令相同；`update` 是 `adopt` 的别名。 ``` npx @byerlikaya/claude-starter-kit@latest update # npx brew upgrade byerlikaya/tap/claude-starter-kit && claude-starter-kit update # Homebrew gh release download --repo byerlikaya/claude-starter-kit -p '*.tgz' && tar xzf claude-starter-kit-*.tgz && bash adopt.sh # tarball ``` 在安装时，套件会将 profile、后端技术栈以及运行的安装程序信息记录到 `.claude/kit.conf` 中，并生成 `.claude/VERSION`。更新程序会读取该记录，并**按照最初安装时的结构**刷新项目：`--backend` 项目不会被强行加上前端 Agents，`--dotnet` 项目也会保留其 `devarch-module` 模式 skill。如果找不到记录，更新程序会根据已安装的文件推导出结构并将其写入。你可以通过对比 `cat .claude/VERSION` 和 `npm view @byerlikaya/claude-starter-kit version` 的结果，来检查是否有待更新的版本。 | | 更新时 | |---|---| | `.claude/` agents · skills · commands · hooks · eval | 从新版本刷新 | | `.claude/DISCIPLINE.md` | **会被覆盖** — 它由套件掌管，所以不要在里面保留你自己的内容 | | `./CLAUDE.md` | 绝不触碰 — 你的项目规则会完全按照你的原意保留 | | `.claude/settings.json` | 以感知 schema 的方式合并；你自己添加的 hooks 和权限设置都会保留 | | 你自己的 agents 和 skills (不带 `-csk` 后缀) | 不受影响 | 与 `adopt` 一样，更新操作需要一个 git repo，并且会落在 `kit-adopt-` 分支上，状态为 staged 且未提交 — 审查 diff，然后 commit 接受或者 reset 丢弃即可。 ## 内部包含什么 - **11 个 agents** — 见上面的表格。 - **30 个 skills** — 作为“如何执行”的单一事实来源，每个领域一个（下方提供完整目录）。 - **6 个 slash 命令** — `/brainstorm` · `/plan` · `/review` · `/ship` · `/handoff` · `/simplify`。 - **Hooks** — `guard-bash.sh` (工具级 gate)、`pre-commit` + `commit-msg` (trace + 密钥扫描)、`context-usage.sh` 和 `session-guard.sh` (会话度量)。 - **CLAUDE.md** — 行为规范、三大原则、工作流、Definition of Done（完成标准）、token 纪律和禁止事项。

完整 skill 目录 — 全部 30 个，由每个 skill 自动生成

| Skill | 作用 | |:--|:--| | `a11y` | 前端无障碍审计 (WCAG)：语义化 HTML、键盘访问、焦点管理、对比度、ARIA、屏幕阅读器。 | | `adr` | 架构决策记录 (ADR)：上下文-决策-后果，用于记录难以轻易撤销的。 | | `api-design` | API 契约设计：资源命名、错误模型、版本控制、分页、向后兼容性、OpenAPI。 | | `brainstorm` | 在计划之前进行发散性探索：将模糊的需求转化为 2-4 个界定范围的可选项 + 命名未知项，选择方向，并交给 spec-planning。 | | `ci-pipeline` | CI pipeline 纪律：lint→build→test→quality→security，fail-fast、确定性构建、密钥处理、PR 门禁。 | | `code-review` | 代码审查纪律：基于严重程度排序，针对变更是否能提升系统整体代码健康度给出有理有据的反馈。 | | `commit-message` | Conventional Commits：读取暂存区的 diff 并提出 `type(scope): summary` 格式的提交信息，必要时附带 body/footer。 | | `db-migration` | 安全地应用 schema migrations：检测工具，按风险对变更进行分类，将破坏性操作挡在批准门之后，在生产环境进行备份，… | | `dependency-audit` | 依赖审计：已知 CVE、开源许可合规性、废弃/过时的 package、lockfile 完整性，以及对每一个新增依赖的理由说明… | | `devarch-module` | DevArchitecture 后端模式：MediatR CQRS handler/command/query，IResult/IDataResult，Autofac AOP 链，FluentValidation，i18n。 | | `docs-writer` | 保持文档与代码同步：当公开 API 或行为发生变化时，更新 README、用法说明及相关文档。 | | `frontend-rn-expo` | 可选，针对特定技术栈：React Native + Expo (prebuild)。 | | `frontend` | 与技术栈无关的前端纪律（web · 移动端 · 桌面端）：组件结构、状态、数据获取、loading/empty/error 状态，… | | `handoff` | 会话交接：当上下文占满、某个阶段结束或话题改变时，向 docs/SESSION_STATE.md 写入一个面向行动的交接说明，… | | `i18n-integrity` | 翻译完整性：确保每一个 key 在每一种语言中都存在，无硬编码字符串，占位符和复数形式保持一致。 | | `incident-runbook` | 生产环境事故响应：诊断 → 缓解 → 解决，随后进行无指责复盘并生成可复用的 runbook。 | | `iterate` | 精益求精直至 Done 的循环：重复进行直到测试通过 + 审查无异常 + 无推迟事项；过程有界。 | | `observability` | 与技术栈无关的可观测性：结构化日志、correlation ids、metrics 和 traces；日志中严禁包含 PII 或密钥。 | | `performance` | 与技术栈无关的性能优化：首先进行测量，找到瓶颈，然后再进行优化。 | | `privacy-compliance` | KVKK/GDPR 审计方法：数据清单、目的/依据/留存、最小化、同意、透明度、数据主体权利、跨境… | | `red-team` | 从攻击者视角对 LLM/agent 防御进行测试：通过不受信任的内容进行指令劫持、数据泄露和工具滥用；验证… | | `reflect` | 在完成重要工作后的回顾性自我审计：未经验证的假设、遗漏的项目、这是否是正确的方法 — 关注发现的问题，而不是代码。 | | `release` | 版本控制与 CHANGELOG：基于 Conventional Commits 映射出的 SemVer、Keep a Changelog 格式、打 tag、预发布门禁。 | | `security-scan` | 与技术栈无关的安全审计：映射攻击面，追踪不受信任的输入至危险调用，揭露依赖项和配置中的缺陷。 | | `sonarqube-check` | SonarQube 质量门禁（不限语言）：0 Bugs · 0 Vulnerabilities · 0 Security Hotspots · 0 Code Smells，构建过程 0 warnings / 0… | | `spec-planning` | Spec-first（规范优先）规划：任务拆解、可衡量的验收标准、依赖顺序、风险优先级。 | | `testing` | 测试的具体操作：金字塔模型、AAA、隔离性、风险覆盖率、确定性。 | | `token-budget` | 上下文/token 纪律：subagent 隔离、output = summary、移至文件、委托阈值、精益的 skills。 | | `trace-scan` | Trace 扫描 (§4.1/§4.2)：在提交之前，扫描暂存区的变更和提交信息中是否存在 AI 痕迹（共同作者 trailers、footers、robot… | | `vps-deploy` | 安全部署到 VPS：runtime 检测、反向代理 + SSL、原子交换、保留上一版本、部署后健康状态门禁，… |

## 会话与 token 管理 助手本身无法运行 `/context`，因此大多数设置只能靠**猜测**会话的占用情况。而本套件是进行测量的。`context-usage.sh` 会从记录中读取上一轮 API 使用情况的真实 token 数量 — 与 `/context` 显示的数据完全一致。`UserPromptSubmit` hook 会在每一轮将其注入；`Stop` hook (`session-guard.sh`) 会在占用率首次突破 **75%** 时发出警告，并在达到 **90%** 时再提醒一次 — 每个阈值仅提醒一次，且绝不会阻断你的操作回合。会话健康度指示行是基于测量结果的，而非猜测。 ### Token 成本 `DISCIPLINE.md` 以及 agent/skill 的描述会被加载到每个会话的上下文中。这部分常驻材料在实际的一轮操作中（针对 11 个 agents 和 28 个 skills）测得占用了 **9,198 个 tokens**；`brainstorm` 和 `reflect` 会在此基础上增加约 660 字节（≈ 280 个 tokens） — 这就是整个纪律层的成本代价。 `smoke-test.sh` 对每个组件（discipline · agent 描述 · skill 描述）强制执行字节预算限制，因此成本绝不会在不知不觉中发生膨胀。预算上限是可以提高的，但只能通过显式编辑 `smoke-test.sh` 来实现。 ## Rule → gate（规则即门禁） | 规则 | 执行机制 | |---|---| | 只有在批准后才能 commit/push — 适用于所有权限模式 | `guard-bash.sh` (PreToolUse) 会弹出一个只有你能回答的批准提示；批准一次后 Claude 就会执行提交。在 `bypassPermissions` 模式下会默认拒绝（关闭）；`CLAUDE_GIT_OK=1` 可用于预先授权 headless 运行 | | 破坏性操作 (reset --hard · force push · rm -rf · --no-verify) | `guard-bash.sh` (在工具层面拦截) | | 远程代码执行 / 权限清除 (`curl…\|bash` · `chmod 777` · `dd of=`) | `guard-bash.sh` (在所有模式下均强制拦截) | | 绕过门禁 (重定向 `core.hooksPath`，或编辑/删除 hook 脚本) | `guard-bash.sh` (shell 端) + `guard-write.sh` (Write/Edit 端) — 能被悄悄移除的门禁算不上是门禁 | | 直接向默认分支提交代码 | `guard-bash.sh` 会在批准提示中予以显示（这是一个警告，而非阻断 — 因为一个全新的项目理应直接在 `main` 上开发） | | 暂存构建/第三方依赖产物或过大的二进制大文件 | `pre-commit` 仓库冗余扫描 (`node_modules/`、`dist/`、`>5 MiB` 等；可通过 `CSK_MAX_FILE_BYTES` 覆盖) | | 暂存了密钥**文件** (整体即为密钥的文件，内容扫描可能会漏掉) | `pre-commit` 密钥文件门禁 (`.env`、`id_rsa`、`*.pem/.key/.p12`、`.npmrc` 等；`.env.example`/`.sample`/`.template` 仍可提交) | | 利用 `-f` 绕过 `.gitignore` 强制添加 (`git add -f`) · 删除 lockfile | `guard-bash.sh` (在工具层面拦截) | | 提交信息中禁止包含 AI 作者痕迹或外部供应商名称 | `pre-commit` + `commit-msg` git hook — 扫描你项目的文件；套件自身的 `.claude/` 目录树可豁免（因为它声明了其配置的工具名称），但对于密钥绝不豁免 | | 禁止提交 API key / token / 私钥 | `pre-commit` 密钥扫描 (`secret-blocklist.txt` + `.secret-allowlist.txt`) | | 会话阈值 | `context-usage.sh` + `session-guard.sh` (Stop hook) | | 常驻上下文保持精简 | `smoke-test.sh` 对每个组件执行字节预算控制 (discipline · agent 描述 · skill 描述) | | 正在运行的会话绝不遵循过期的规则 | `context-usage.sh` 会将 `.claude/VERSION` 与当前会话启动时的版本进行比对，并给出提示 | | 质量门禁 (SonarQube 项目 — 不限语言) | `sonarqube-check` + `/ship` | 这些门禁通过 `settings.json` 和 git `core.hooksPath` 进行武装；`smoke-test.sh` 会在每次更改后验证它们是否就绪。 ## 验证 ``` bash .claude/eval/smoke-test.sh # structure, frontmatter, gate integrity bash .claude/eval/routing-eval.sh # does an example prompt route to the right agent/skill ``` ## 工作流 `/plan` (范围不明确) → 专家 agents 构建 → `/review` (安全 · 质量 · 测试) → `/ship` (DoD 门禁；提出提交建议，等待批准) → 当上下文填满时，执行 `/handoff` → `/clear`。 ## 扩展 当你添加 agent 或 skill 时，请遵循 `AGENT_TEMPLATE.md` 契约：frontmatter（名称 · 描述 + 触发短语 · 最小权限工具 · 模型层级）以及正文（时机 → 专家立场 → 方法/skill → 协调 → DoD → 输出 & 上下文 → 错误/升级 → 示例 → 约束）。 ## 许可证与归属 MIT — 详见 [LICENSE](LICENSE)。纪律层是基于以下上游源构建的： - **[DevArchitecture](https://github.com/DevArchitecture/DevArchitecture)** — 后端模式 (MediatR CQRS / IResult / AOP)，仅作为模式参考。 - **[multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills)** — 处于纪律核心位置的四个工作原则。 - **[google/eng-practices](https://github.com/google/eng-practices)** — `code-review` skill，经过提炼和重述 (CC-BY 3.0)。

标签：AI智能体, AI辅助编程, Claude, Cutter, CVE检测, Git, MITM代理, SOC Prime, 代码审查, 多人体追踪, 开发工具, 暗色界面