Merge pull request 'add 中文核心分析 + README 改写' (#1) from hermes into main

ANALYSIS.md

@@ -0,0 +1,188 @@
+# addyosmani/agent-skills 中文分析
+
+> 镜像仓库 + 个人分析。本仓存的是**核心结构梳理 + 场景依赖评估**，不是上游代码搬运。
+> 上游代码请访问 [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)。
+
+---
+
+## 1. 仓库元数据（GitHub API 实测 · 2026-06-13）
+
+| 字段 | 值 |
+|------|-----|
+| full_name | addyosmani/agent-skills |
+| description | Production-grade engineering skills for AI coding agents. |
+| ⭐ stars | **56,856** |
+| forks | 6,129 |
+| open issues | 129 |
+| language | Shell（实际为 markdown + slash command 脚本） |
+| size | 328 KB（**正常**，不是异常大） |
+| license | MIT |
+| 创建 | 2026-02-15（**4 个月**冲到近 6 万 star） |
+| 最近更新 | 2026-06-11（**2 天前**，活跃维护中） |
+| topics | agent-skills / antigravity-ide / claude-code / cursor / skills |
+
+**作者**：**Addy Osmani** — Google Chrome 团队工程师、Web 性能领域知名作者。
+**信号验证**：作者身份与高 star 数对得上，README 跟 API 字段对得上，**无营销文特征**。✅ 已交叉验证。
+
+---
+
+## 2. 核心结构
+
+### 2.1 6 步生命周期
+
+```
+DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP
+/spec   /plan  /build  /test   /review  /ship
+```
+
+每个阶段对应一个 slash command，**自动激活相应 skills**。
+
+### 2.2 7 个 slash command
+
+| 用途 | 命令 | 核心原则 |
+|------|------|----------|
+| 定义要建什么 | `/spec` | Spec before code |
+| 计划怎么建 | `/plan` | 小颗粒、原子化任务 |
+| 增量实现 | `/build` | 一次一片 |
+| 证明能用 | `/test` | Tests are proof |
+| 合并前审查 | `/review` | 改善代码健康度 |
+| 简化代码 | `/code-simplify` | 清晰 > 巧妙 |
+| 上生产 | `/ship` | 更快 = 更安全 |
+
+**`/build auto` 模式**：你批准一次计划，剩下的全自动跑。每个任务仍是测试驱动 + 单独 commit，**失败 / 高风险步骤会暂停**等你。
+
+### 2.3 23 个 skill 模块
+
+| 类别 | skill 名称 |
+|------|-----------|
+| 架构设计 | api-and-interface-design、context-engineering、planning-and-task-breakdown |
+| 质量保障 | test-driven-development、code-review-and-quality、code-simplification |
+| 工程化 | ci-cd-and-automation、debugging-and-error-recovery、observability-and-instrumentation |
+| 安全 | security-and-hardening |
+| 流程 | spec-driven-development、incremental-implementation、deprecation-and-migration |
+| 前端 | frontend-ui-engineering、browser-testing-with-devtools |
+| 文档 | documentation-and-adrs、source-driven-development |
+| 进阶 | **doubt-driven-development**（怀疑式开发）、idea-refine、interview-me |
+
+### 2.4 支持的 AI Agent
+
+- **Claude Code**（推荐）
+- Cursor
+- OpenCode
+- Gemini CLI
+- Antigravity IDE
+
+---
+
+## 3. 场景依赖评估
+
+### 3.1 对我的 Windows 主力机 + 电机控制算法落地 ⭐⭐⭐⭐⭐ **强推荐**
+
+**痛点**：让 AI 写 STM32 / 嵌入式代码，最怕"AI 自由发挥，编译都过不了"。
+
+**这套怎么解**：
+- `/spec` 强制先把需求写清楚（电机型号 / 通信协议 / 采样率 / 安全约束）
+- `/plan` 把 FOC 算法拆成可执行的小任务（Clark 变换 → Park 变换 → SVPWM → PID 调参）
+- `/build` 增量写，**每步可编译可烧录**
+- `/test` 验证：编译过 + 仿真过 + 实际跑
+
+**具体装法**（Claude Code）：
+```
+/plugin marketplace add addyosmani/agent-skills
+/plugin install agent-skills@addy-agent-skills
+```
+
+### 3.2 对 AI 编程实战 / Claude Code / Codex 协作 ⭐⭐⭐⭐ **推荐**
+
+**场景**：让多个 AI agent 协作写代码（Claude 写架构 → Codex 写测试 → 人类 review）。
+
+**价值**：
+- 7 个 slash command 把"工作流"标准化，**AI 不会自由发挥**
+- 23 个 skill 覆盖"代码从需求到上生产的全流程"
+- `/build auto` 模式让 AI 自主跑长任务，**人类只在关键节点介入**
+
+**风险**：
+- 依赖外部作者持续维护（4 个月 6 万 star，**信号强但不能 100% 保证长期更新**）
+- 跟 Hermes 的"AI 协作约定"（架构师 + 产品经理定位）有重叠，**二选一或混用需要先想清楚**
+
+### 3.3 对日常中文编程 / 数据处理 ⭐⭐ **可选**
+
+**适合度低的原因**：
+- 仓库**主推英文场景**，中文代码注释 / 文档的 skill 没有
+- 嵌入式 / Web 性能优化的 skill 偏专业，**日常 Python 脚本用不上**
+- 23 个 skill 太多，**学习成本高于收益**（除非你 50% 时间在写 AI 协作代码）
+
+**建议**：日常写小脚本**不装**，专门做 AI 协作项目再装。
+
+### 3.4 对我自己的 Herme 体系 ⭐⭐⭐ **可参考**
+
+**重叠 / 互补点**：
+- `ai_road` 仓库的 `00-基础环境篇` 有"AI 协作约定"（零、CLAUDE.md 修改协议 + 一~九 行动偏好）—— **是策略层**
+- `agent-skills` 仓库是 7 command + 23 skill —— **是战术层**
+- **两者应该并存**：策略管"该不该做 / 什么时候做"，战术管"具体怎么一步步做"
+
+**可以反哺**：
+- 把 `agent-skills` 的 `/spec` `/plan` `/build` 思路**翻译成中文版**，沉淀进 `ai_road/01-AI编程实践篇/` 作为方法论参考
+- 但**不强制绑定**——Hermes 的灵活度比这套工作流高
+
+---
+
+## 4. 安装到 Claude Code
+
+```bash
+# 推荐（SSH）
+/plugin marketplace add addyosmani/agent-skills
+/plugin install agent-skills@addy-agent-skills
+
+# 没 SSH key 时（HTTPS 强制）
+/plugin marketplace add https://github.com/addyosmani/agent-skills.git
+/plugin install agent-skills@addy-agent-skills
+```
+
+装完后：
+- Claude Code 会自动识别 slash command
+- 在合适场景**自动激活**相关 skill
+- 装一次，**所有项目通用**
+
+---
+
+## 5. 风险与限制
+
+| 风险 | 说明 |
+|------|------|
+| **依赖外部作者** | 4 个月 6 万 star 强信号，但作者是 Google 工程师（非 Google 官方仓库），长期维护需观察 |
+| **skill 过载** | 23 个 skill 一次性激活，**对短任务反而拖慢**（AI 要判断该用哪个） |
+| **跟现有约定冲突** | 跟 Hermes 的"AI 是架构师不是执行者"定位有张力，混用需先想清楚 |
+| **跨 Agent 兼容性** | Claude Code 适配最好，Cursor / OpenCode 兼容但功能可能不全 |
+| **国内市场** | 仓库在 GitHub，国内访问可能慢或需代理 |
+
+---
+
+## 6. 跨源验证
+
+| 维度 | 信号 | 结论 |
+|------|------|------|
+| README 真实性 | 命令清单、ASCII 图、目录结构都对得上 | ✅ |
+| API 数据 vs 仓库描述 | size / star / forks 数量级合理 | ✅ |
+| 维护活跃度 | 2 天前最新 commit，PR 持续 merge | ✅ |
+| 营销文检测 | 描述用 "Production-grade" 略大，但内容扎实（命令清单 + skill 模块都有实质） | ✅（非营销） |
+| 作者背景 | Addy Osmani 是 Google Chrome 团队工程师，Web 性能领域知名 | ✅（非匿名） |
+| 增长曲线 | 4 个月 6 万 star（**异常快**） | ⚠️ 关注后续是否可持续 |
+
+---
+
+## 7. 总结
+
+**一句话**：Google Chrome 工程师 Addy Osmani 个人维护的"AI 编程高级工程师工作流"仓库，4 个月 6 万 star，跨 4 个 AI Agent 工具，**对电机控制 + AI 协作场景强推**，日常编程可选装。
+
+**我的选择**：
+- ✅ 装到 Claude Code（前提是你确认跟现有 AI 协作约定不冲突）
+- ✅ 抽时间把 `/spec` `/plan` `/build` 思路**翻译进 `ai_road/01-AI编程实践篇/`**
+- ❌ 不强推——它适合"AI 主导写代码"的工作流，不适合"AI 是顾问"的工作流
+
+---
+
+**分析版本**：v1.0 · 2026-06-13
+**数据来源**：GitHub API + MIT Tech Review 跨源
+**维护者**：Hermes Agent（hermes 分支）
+**下次复审**：star 突破 8 万 或 作者停止维护任一触发

README.md

@@ -1,3 +1,26 @@
 # addyosmani-agent-skills-mirror
 
-addyosmani/agent-skills 镜像 + 中文分析。Google Chrome 团队工程师 Addy Osmani 维护的 AI 编程 Agent 工程规范集
+> **本仓是镜像 + 分析，不是代码搬运。**
+> 上游：[addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)
+
+## 仓库内容
+
+| 文件 | 用途 |
+|------|------|
+| **ANALYSIS.md** | 中文核心结构分析 + 场景依赖评估（**根目录显眼位置**） |
+| upstream/ | （未来）按需同步的上游文件 |
+
+## 镜像原则
+
+- **本仓不持续同步上游代码**——上游更新太快（每天几个 commit），同步成本高
+- 只在**重要版本**（如 v1.0 发布）同步关键文件到 `upstream/`
+- **ANALYSIS.md 是核心资产**——记录的是"为什么这个仓库对 hwd32 有用"，不是"它有什么"
+
+## 分析版本
+
+- v1.0（2026-06-13）—— 首版
+
+## 关联
+
+- 主开发仓：[hwd32/ai_road](http://10.166.166.252:3000/hwd32/ai_road)
+- GitCode 镜像：[hwd32/addyosmani-agent-skills-mirror](https://gitee.com/hwd32/addyosmani-agent-skills-mirror)