diff --git a/andrej-karpathy-skills-notes.md b/andrej-karpathy-skills-notes.md new file mode 100644 index 0000000..62b3867 --- /dev/null +++ b/andrej-karpathy-skills-notes.md @@ -0,0 +1,107 @@ +# Andrej Karpathy Skills 安裝與使用筆記 + +## 基本資訊 + +- **專案**: https://github.com/forrestchang/andrej-karpathy-skills +- **作者**: Forrest Chang(forrestchang) +- **授權**: MIT +- **類型**: Claude Code 外掛(plugin/skill)+ 可貼到 CLAUDE.md 的規則集 +- **靈感來源**: [Andrej Karpathy 對 LLM coding 缺陷的觀察](https://x.com/karpathy/status/2015883857489522876) +- **安裝日期**: 2026-04-19 + +## 是什麼 + +一份讓 Claude Code(以及 Cursor)寫 code 時更「克制、精準、以目標為導向」的行為準則。核心觀點:**LLM 擅長為了達成目標而反覆迭代,所以把「目標」定義清楚,比教它怎麼寫 code 更重要。** + +### 四大原則 + +1. **Think Before Coding(先思考再動手)** + - 明確說出假設;不確定就問 + - 看到多種詮釋時攤開來,不要偷偷選 + - 有更簡單的做法就直說,該推回時推回 + +2. **Simplicity First(簡單優先)** + - 只寫能解決問題的最小程式碼 + - 不做沒要求的功能、抽象、彈性、錯誤處理 + - 200 行能壓到 50 行就重寫 + +3. **Surgical Changes(外科手術式修改)** + - 只動必要的部分,別順手「改進」相鄰程式碼 + - 不要 refactor 沒壞的東西;維持原有風格 + - 每一行變更都要能對應到使用者的請求 + +4. **Goal-Driven Execution(目標驅動執行)** + - 把任務轉成可驗證的成功條件,例如: + - 「加驗證」→「寫失敗測試,讓它通過」 + - 「修 bug」→「寫能重現 bug 的測試,讓它通過」 + - 多步驟任務先列計畫,每步附 verify 檢查項 + +## 安裝方式 + +### 方法 A:Claude Code Plugin(推薦) + +在 Claude Code 對話中執行: + +```text +/plugin marketplace add forrestchang/andrej-karpathy-skills +/plugin install andrej-karpathy-skills@karpathy-skills +/reload-plugins +``` + +### 方法 B:直接放到專案 CLAUDE.md + +```bash +# 新專案 +curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md + +# 既有 CLAUDE.md 附加 +echo "" >> CLAUDE.md +curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md +``` + +### 方法 C:Cursor + +專案 repo 內附 `.cursor/rules/karpathy-guidelines.mdc`,放進你的專案即可。詳見原 repo 的 `CURSOR.md`。 + +## 與現有 karpathy-guidelines skill 的差異 + +本機 `~/.claude/skills/karpathy-guidelines/SKILL.md` 已存在一份同概念 skill(Anthropic / 預設安裝),內容涵蓋完全相同的四大原則。 + +| 比較項 | 本機既有 skill | forrestchang plugin | +|--------|---------------|---------------------| +| 位置 | `~/.claude/skills/karpathy-guidelines/` | plugin marketplace | +| 格式 | 單檔 SKILL.md | plugin 套件 | +| 可更新 | 手動 | `/plugin update` | +| 內容 | 四原則 + trade-off 說明 | 四原則 + Cursor 支援 | + +**實務建議**:兩者任擇其一即可,重複安裝會讓 skill 名稱衝突。 + +- 若只想在 Claude Code 使用並保持簡單:維持現有 skill。 +- 若要跨 Cursor / 多機器同步並接受 plugin 更新機制:改裝 plugin 版本。 +- 若要在特定專案強制執行:方法 B 把 CLAUDE.md 放進 repo,團隊成員都會讀到。 + +## 成功指標(來自原作者) + +- 不必要的 diff 變動變少 +- 第一次嘗試就產出更簡潔的程式碼 +- 實作前會先提釐清問題 +- PR 更小、更聚焦 + +## 常用檢查 + +```bash +# 既有 skill +cat ~/.claude/skills/karpathy-guidelines/SKILL.md + +# Plugin 安裝後 +ls ~/.claude/plugins/marketplaces/ | grep -i karpathy +cat ~/.claude/plugins/known_marketplaces.json + +# 在 Claude Code 查看 skill 列表 +/skill list # 或直接輸入 / 查看建議 +``` + +## 備註 + +- Karpathy 原推文提醒的幾個 LLM 缺陷:過度抽象、加非必要功能、改到不該改的地方、沒問就猜。這份 skill 就是針對這些的反制。 +- 文件開頭已聲明 trade-off:偏向「謹慎優先於速度」;瑣碎任務自行拿捏。 diff --git a/claude-hud-notes.md b/claude-hud-notes.md new file mode 100644 index 0000000..389e648 --- /dev/null +++ b/claude-hud-notes.md @@ -0,0 +1,114 @@ +# Claude HUD 安裝與使用筆記 + +## 基本資訊 + +- **專案**: https://github.com/jarrodwatts/claude-hud +- **作者**: Jarrod Watts +- **授權**: MIT +- **類型**: Claude Code 外掛(statusline 增強) +- **用途**: 在 Claude Code 終端狀態列即時顯示 context 用量、執行中的工具/agent、待辦進度、git 狀態等資訊 +- **需求**: Claude Code v1.0.80+、Node.js 18+ 或 Bun +- **本機環境**: Claude Code 2.1.114、Node v25.8.2、Bun 1.3.11 ✅ +- **安裝日期**: 2026-04-19 + +## 是什麼 + +Claude HUD 把原本單純的 statusline 變成 HUD(Heads-Up Display),即時顯示: + +- **Project path**:可顯示 1–3 層目錄 +- **Context 健康度**:context window 用量長條,顏色會隨用量變化 +- **Tool activity**:正在跑的 Read/Edit/Grep 等工具與次數 +- **Agent 追蹤**:活躍 subagent 名稱、模型、耗時 +- **Todo 進度**:任務完成比例 +- **Git 狀態**:branch、dirty、ahead/behind、檔案變更數 +- **Usage limits**:Claude 訂閱用戶的每小時與 7 日配額 + +## 安裝步驟 + +在 Claude Code 對話中依序執行: + +```text +/plugin marketplace add jarrodwatts/claude-hud +/plugin install claude-hud +/reload-plugins +/claude-hud:setup +``` + +接著**重新啟動 Claude Code**,讓 `statusLine` 設定生效。 + +### 平台注意事項 + +- **Linux**:若 install 時出現 cross-device link 錯誤,先設定 `TMPDIR=~/.cache/tmp` 再安裝。 +- **Windows**:若 setup 提示找不到 JavaScript runtime,請先裝 Node.js LTS。 +- **macOS**:無額外步驟。 + +## 設定 + +互動式設定: + +```text +/claude-hud:configure +``` + +或直接編輯: + +```text +~/.claude/plugins/claude-hud/config.json +``` + +### 預設 Preset + +| Preset | 內容 | +|--------|------| +| Full | 全部資訊開啟 | +| Essential | activity + git,少雜訊 | +| Minimal | 只顯示模型名稱與 context bar | + +### 可調整項目 + +- 語言:英文 / 中文 +- 版面:多行展開 或 單行緊湊 +- Path 深度:1–3 層 +- Git 顯示:dirty、ahead/behind、變更檔案數 +- 顯示切換:tools、agents、todos、duration、memory、cost +- 配色:16 個顏色值可自訂 + +## 顯示範例 + +**預設兩行版面:** + +```text +[Opus] │ my-project git:(main*) +Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h) +``` + +**啟用 activity 行(選用):** + +```text +◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2 +◐ explore [haiku]: Finding auth code (2m 15s) +▸ Fix authentication bug (2/5) +``` + +## 常用檢查與移除 + +```bash +# 檢查外掛目錄 +ls ~/.claude/plugins/marketplaces/claude-hud 2>/dev/null + +# 檢查設定 +cat ~/.claude/plugins/claude-hud/config.json 2>/dev/null +``` + +在 Claude Code 中移除: + +```text +/plugin uninstall claude-hud +/plugin marketplace remove jarrodwatts/claude-hud +``` + +## 備註 + +- HUD 資料來自 Claude Code 的 statusLine hook,因此需要重啟 Claude Code 才會套用新的 statusLine 配置。 +- 若 context bar 顯示與 `/context` 略有落差,屬預期:HUD 讀的是 hook 傳入的近似值。 +- 多行版面在較窄的終端(寬度 < 80)可能換行,建議改用 compact 或 minimal preset。 diff --git a/superpowers-notes.md b/superpowers-notes.md new file mode 100644 index 0000000..d8e8c06 --- /dev/null +++ b/superpowers-notes.md @@ -0,0 +1,115 @@ +# Superpowers 安裝與使用筆記 + +## 基本資訊 + +- **專案**: https://github.com/obra/superpowers +- **作者**: Jesse Vincent(obra)/ Prime Radiant +- **授權**: MIT +- **類型**: Claude Code / Cursor / Gemini CLI / GitHub Copilot CLI 外掛 +- **用途**: 為編碼代理(coding agent)提供結構化開發方法論的可組合 skills +- **官方社群**: Discord、GitHub Issues、primeradiant.com/superpowers +- **安裝日期**: 2026-04-19 + +## 是什麼 + +Superpowers 是一套專為 AI 編碼代理設計的軟體開發方法論框架。它不讓代理直接寫程式,而是透過一組可組合(composable)的 skills,引導代理依序走完設計、規劃、實作、測試、審查等階段,內建品質檢查點。 + +核心理念: +- 系統化優先於臨時應變(Systematic over ad-hoc) +- 以測試驅動開發(TDD)為基礎 +- 降低複雜度,追求簡單 +- 用證據驗證,而非假設 + +## 安裝 + +### Claude Code(官方 Marketplace,推薦) + +在 Claude Code 對話中執行: + +```text +/plugin install superpowers@claude-plugins-official +``` + +本機 `claude-plugins-official` marketplace 已位於: +`~/.claude/plugins/marketplaces/claude-plugins-official/` + +### Claude Code(Superpowers 自家 Marketplace) + +```text +/plugin marketplace add obra/superpowers-marketplace +/plugin install superpowers@superpowers-marketplace +``` + +### Cursor + +```text +/add-plugin superpowers +``` + +### GitHub Copilot CLI + +```bash +copilot plugin marketplace add obra/superpowers-marketplace +copilot plugin install superpowers@superpowers-marketplace +``` + +### Gemini CLI + +```bash +gemini extensions install https://github.com/obra/superpowers +gemini extensions update superpowers # 更新 +``` + +## 核心工作流程(七個階段) + +1. **Brainstorming(腦力激盪)** — 透過發問釐清需求與目標 +2. **Git Worktrees** — 建立隔離的開發分支 +3. **Planning(規劃)** — 將工作切成 2–5 分鐘、junior 開發者可執行的小任務 +4. **Implementation(實作)** — 以 subagent 執行,搭配兩階段 review +5. **Testing(測試)** — 強制 red-green-refactor TDD 循環 +6. **Code Review** — 對照規格驗證實作 +7. **Completion(收尾)** — 合併或歸檔 + +## Skills 清單 + +### 測試與品質 +- TDD(RED-GREEN-REFACTOR) +- 系統化除錯(4 階段根因分析) +- 完成前驗證(verification before completion) + +### 規劃與協作 +- Brainstorming 與設計精煉 +- 撰寫詳細實作計畫 +- 依計畫執行並設檢查點 +- Subagent 驅動開發 + 兩階段審查 +- Code review 請求/回覆流程 +- Git worktree 管理 +- 開發分支收尾 + +### Meta +- 撰寫符合最佳實務的新 skill +- Skills 系統入門 + +## 使用方式 + +安裝完成後,在 Claude Code 中 skills 會依對話情境自動啟用。也可以用 `/` 查看並手動觸發特定 skill。 + +進入典型開發任務時,Superpowers 會先要求對話釐清需求、產出 design doc,再分解任務、建立 worktree,接著才真正開始寫 code。 + +## 常用檢查指令 + +```bash +# 檢查 marketplace +ls ~/.claude/plugins/marketplaces/ + +# 看哪些 marketplace 已加入 +cat ~/.claude/plugins/known_marketplaces.json + +# 看 superpowers 是否在 marketplace 清單 +grep -l "superpowers" ~/.claude/plugins/marketplaces/claude-plugins-official/.claude-plugin/marketplace.json +``` + +## 備註 + +- Superpowers 的設計偏好「先對齊再寫 code」,如果你要的是快速一次性 hack,它可能會顯得繁瑣;適用於需要品質與可維護性的正式任務。 +- 方法論強調由人類確認設計稿再進入實作,互動次數會比裸 agent 多。