<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Chuan 建權 on Medium]]></title>
        <description><![CDATA[Stories by Chuan 建權 on Medium]]></description>
        <link>https://medium.com/@chienchuanwang?source=rss-8169ac429c8c------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*ruKBzFlKcKd079DVDhM0AA.jpeg</url>
            <title>Stories by Chuan 建權 on Medium</title>
            <link>https://medium.com/@chienchuanwang?source=rss-8169ac429c8c------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Tue, 17 Nov 2026 05:09:20 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@chienchuanwang/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Claude 工程師教你怎麼用 skills：如何分享你的 skills 給全世界]]></title>
            <link>https://medium.com/@chienchuanwang/claude-%E5%B7%A5%E7%A8%8B%E5%B8%AB%E6%95%99%E4%BD%A0%E6%80%8E%E9%BA%BC%E7%94%A8-skills-%E5%A6%82%E4%BD%95%E5%88%86%E4%BA%AB%E4%BD%A0%E7%9A%84-skills-%E7%B5%A6%E5%85%A8%E4%B8%96%E7%95%8C-2dfda95b244e?source=rss-8169ac429c8c------2</link>
            <guid isPermaLink="false">https://medium.com/p/2dfda95b244e</guid>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[skills]]></category>
            <category><![CDATA[claude-code]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[claude]]></category>
            <dc:creator><![CDATA[Chuan 建權]]></dc:creator>
            <pubDate>Sat, 28 Mar 2026 09:18:21 GMT</pubDate>
            <atom:updated>2026-03-28T09:19:15.056Z</atom:updated>
            <content:encoded><![CDATA[<p>一如我們可以蒐集（搜刮？）別人已經做好的好用 skills，我們也可以把自己寫好的 skills 提供給他人使用。</p><p>這時候我們心中可能會冒出幾種聲音：</p><blockquote>「我不好意思分享自己的 skills 啦！」</blockquote><blockquote>「別人的 skills 已經很好用了，幹嘛用我的？」</blockquote><blockquote>「我這麼嫩，寫的 skills 一定很爛，分享出去會被嘲笑的！」</blockquote><p>別擔心，我跟你一樣，大多時候我們都是「寫給自己用」，不過跟使用 lint 工具一樣，進行團隊協作時，為了統一大家的格式、縮排，我們傾向對 lint 進行相同的設定。</p><p>同樣地，有時候團隊之間共用指定的 skill，可以確保大家盡可能在開發上維持一致的流程，並產出風格接近的成果。</p><p>這種相對「私底下」的分享方式，我們可以將 ./.claude/skills 透過 Git 等版本控制工具進行版控，然後透過 GitHub repo 分享給團隊成員共同使用。</p><h3>將 skills 做成 plugin</h3><p>如果只是在小團隊內分享，大家開發的專案數量相同重疊，那透過 repo 分享確實簡單方便，但每一個 skills 的存在都會增加 agent 與 model 理解上下文（context）的負擔，當開發的規模與專案數量增加後，更適當的做法應該是將這些 skills 打包成 plugin，並註冊到 marketplace 讓團隊成員可以使用 CLI 進行查看，並根據各自的需求安裝。</p><p>這邊的 marketplace 可以想像成是 skills 的百貨公司，雖說是百貨公司，並不代表我們上傳的 skills 必須公諸於世，更像是有系統地管理我們所擁有的 skills，所以這個 marketplace 也可以存放在私人的 repo 空間裡。</p><p>以 Anthropic 官方提供的 <a href="https://github.com/anthropics/skills">skills</a> repo 為例：</p><ol><li>在 Claude Code 輸入 /plugin marketplace add anthropics/skills，將這個官方的 marketplace 註冊成為我們 Claude Code 擁有的其中一個 marketplace。</li><li>完成安裝後，在 Claude Code 輸入 /plugin，並透過左右方向鍵切換到 Marketplaces 的分頁，我們可以在列表看到剛剛註冊好的 anthropic-agent-skills。</li><li>進入到 anthropic-agent-skills 裡面，可以選擇 Browse plugins 來查看這個 marketplace 所提供的 plugins。</li><li>任意選取一個 plugin 便可以開始進行安裝。</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Awfbpd262Zxijcr-4cMrRw.png" /><figcaption>/plugin 的 Marketplaces 的列表</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*qDlZOIV1ennqYKnC0h8GYA.png" /><figcaption>Anthropic 官方的 Marketplace 提供了三個 plugins</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*mmNaUuijhunaXXKubwiu5w.png" /><figcaption>選取所需的 plugin 並決定如何安裝</figcaption></figure><h3>Marketplace 的原理</h3><p>我們可能會以為註冊 marketplaces 是不是等於「在電腦裡全域安裝這些 plugin」，然後針對指定專案開啟特定的 plugin。</p><p>事實上，marketplace 只是一個名為 marketplace.json 的「索引」文件，它告訴我們：</p><ul><li>這個 marketplace 的名稱與擁有者聯絡資訊</li><li>這個 marketplace 所提供的 plugin 列表</li><li>每個 plugin 的名稱、描述、內容、安裝來源、所擁有的 skills 等</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*LoZ35vtzjwaweTEr1atrTw.png" /><figcaption>marketplace.json 的局部內容</figcaption></figure><p>理解了 marketplace 的原理後，我們也可以透過自己的 repo 來建立個人的 marketplace，為自己收集到的 skill 進行建檔管理。</p><blockquote><em>marketplace.json 的詳細內容可參考 </em><a href="https://github.com/anthropics/skills/blob/main/.claude-plugin/marketplace.json"><em>Anthropics/skills/marketplace.json</em></a><em>。</em></blockquote><p>根據 Claude 工程師的分享，Anthropic 內部並沒有一個專門審核 marketplace 的小組，而是讓來自各方的使用者自行決定「哪些 marketplace 是值得信賴的」、「哪些 skills 是有用的」。</p><p>一旦使用者決定想要「上架」自己的 skill 至某個特定的 marketplace，可以透過 Pull Request (PR) 的方式，讓自己的 skill 成為該 marketplace 的其中一個 plugin。</p><p>目前比較可惜的是，marketplaces 目前還不支援「依賴管理（dependency management）」，也就是說，如果我們有一個「上傳檔案的 skill」，然後有另外一個「csv 檔案生成並上傳的 skill」，很顯然後者必須依賴前者才能正常運作，只是目前 marketplace 還無法表示出「依賴關係」。</p><p>現行只能透過在對話中提及這個指定的「依賴 skill」，在已經有安裝該 skill 的狀況下，讓 agent 可以自主觸發這個 skill。</p><h3>如何得知 skills 的使用狀況</h3><p>剛開始使用一個新工具時，難免我們什麼都想試試，但時間久了會發現，用來用去偏愛的 skills 固定就那幾個，在 Anthropic 內部會透過 PreToolUse hook 來記錄每個 skill 的使用次數，藉此得知哪些 skills 比較受歡迎，哪些 skill 早就被大家打入冷宮。</p><blockquote><em>Claude 工程師 Thariq 有提供 PreToolUse 的範例程式碼：</em><a href="https://gist.github.com/ThariqS/24defad423d701746e23dc19aace4de5"><em>measure-skills.bash</em></a><em>。</em></blockquote><p>也是因為同事分享了 <a href="https://x.com/trq212/article/2033949937936085378">Lessons from Building Claude Code: How We Use Skills</a> 這篇好文，我才有機會仔細審視自己在開發上的習慣，像是有些指令、提示詞明明可以寫成 skill，卻因為懶得鑽研與搜尋 skill，寧可每次浪費時間手動輸入，而不肯痛一次來優化這個工作流程。</p><p>與其說 skills 要取代 MCP 來改變整個開發生態，我更覺得 skills 是一種釋放我們生產力的思維，像是哆啦 A 夢的記憶吐司，我們需要哪個能力就吃哪片吐司，還不用擔心會吃太飽。</p><p>如果喜歡這篇文章：</p><ul><li>可以給我一個掌聲，並且追蹤我的 <a href="https://medium.com/@chienchuanwang">Medium</a> 與 <a href="https://github.com/chienchuanw">GitHub</a>！</li><li>歡迎在文章下方留言分享你的經驗或想法，我們一起進步！</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2dfda95b244e" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Claude 工程師教你怎麼用 skills：寫 skills 該注意什麼事]]></title>
            <link>https://medium.com/@chienchuanwang/claude-%E5%B7%A5%E7%A8%8B%E5%B8%AB%E6%95%99%E4%BD%A0%E6%80%8E%E9%BA%BC%E7%94%A8-skills-%E5%AF%AB-skills-%E8%A9%B2%E6%B3%A8%E6%84%8F%E4%BB%80%E9%BA%BC%E4%BA%8B-4ce4e07f959d?source=rss-8169ac429c8c------2</link>
            <guid isPermaLink="false">https://medium.com/p/4ce4e07f959d</guid>
            <category><![CDATA[claude-code]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[claude]]></category>
            <category><![CDATA[skills]]></category>
            <dc:creator><![CDATA[Chuan 建權]]></dc:creator>
            <pubDate>Fri, 27 Mar 2026 18:04:01 GMT</pubDate>
            <atom:updated>2026-03-27T18:04:01.798Z</atom:updated>
            <content:encoded><![CDATA[<p>繼上一篇〈<a href="https://medium.com/@chienchuanwang/claude-%E5%B7%A5%E7%A8%8B%E5%B8%AB%E6%95%99%E4%BD%A0%E6%80%8E%E9%BA%BC%E7%94%A8-skills-%E6%80%8E%E5%80%91%E5%A5%BD%E5%A5%BD%E5%88%86%E9%A1%9E-skills-1391d7f5701f">Claude 工程師教你怎麼用 skills：怎們好好分類 skills</a>〉我們認識了如何分類 skills，這一篇我們來學習打造 skills 需要注意的細節，未來在打造自己專用的 skills 時，也可以少踩一些雷。</p><blockquote><em>Anthropic 最近也推出了 </em><a href="http://github.com/anthropics/claude-plugins-official/tree/main/plugins/skill-creator"><em>Skill Creator</em></a><em> 的 plugin 幫助我們更快創造一個 skill。</em></blockquote><h3>Don’t State the Obvious</h3><blockquote>說重點</blockquote><p>用 Claude Code 開發到現在，想必大家都知道它有多聰明，甚至比我們更清楚專案的程式碼架構與預設通用的處理方式，所以當我們要撰寫一個新的 skills，「著重在那些能改變 AI 預設行為的具體規則、限制與偏好」，尤其是希望它避免一些的常見風格與行為模式。</p><p>如果曾經有用 agent 進行網站的 UI 設計，大概知道某些風格帶著一股濃濃的「AI 味」，像是藍紫色的漸層、特愛使用 emoji，這時候我們要寫一個前端設計用的 skill，大概會長這樣：</p><pre>- 禁止使用 Inter font<br>- 避免 linear gradient（特別是 purple/blue）<br>- spacing 必須偏緊（不是 SaaS 寬鬆風格）<br>- button 不使用 rounded-full</pre><h3>Build a Gotchas Section</h3><blockquote>紀錄注意事項</blockquote><p>Agent 跟我們一樣會犯錯，那身為人類的我們是如何避免再次犯下同樣的錯誤呢？要嘛是痛到我們這輩子都不可能忘記，要嘛是紀錄下來，下次遇到類似的狀況時，可以回去看看之前是怎麼處理的。</p><p>同樣地，我們也可以將那些 agent 曾經犯下的錯誤記錄在 SKILL.md 裡的 Gotchas 區塊，每當我們開發過程中告訴 agent：「這邊你做錯了，應該怎樣怎樣怎樣」，也可以順手把這些紀錄回 SKILL.md，擴充 agent 對於這些情境的判斷與處理能力。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Ju8LKHJR7FK_mX-t56Q-eg.jpeg" /><figcaption>時常更新 skills 的 Gotchas 區塊</figcaption></figure><h3>Use the File System &amp; Progressive Disclosure</h3><blockquote>善用檔案系統結構並漸進式提供資訊</blockquote><p>前一篇文章我們有提到，許多人對於 skills 最大的誤解之一是「把它當作是單純的 markdown 檔案」，但其實 skills 的內容可以包含 assets、scripts 等多種類型的檔案，所以與其一次把所有資訊塞在 SKILL.md，讓 agent 抓不著重點，更好的做法是在 SKILL.md 說明這個 skill 的結構與使用方式，並在對應的情境去閱讀指定的檔案。</p><p>舉例來說，我們可以將「API 的函式定義、參數說明、用法範例」等細項都放在 reference/api.md 中，並在 SKILL.md 告知 agent 若果需要查看 API 的詳細資訊，可以閱讀 reference/api.md，避免 agent 在一開始就過多的資訊干擾，稀釋了本來最該關注的任務。</p><pre># Skill 的參考架構<br>playwright-verifier/<br>│<br>├── SKILL.md                 ← # 入口（最重要）<br>│<br>├── references/              ← # 按需讀取（Progressive Disclosure）<br>│   ├── api.md<br>│   ├── selectors.md<br>│   └── assertions.md<br>│<br>├── scripts/                 ← # 可執行工具（Verification 核心）<br>│   ├── run-test.ts<br>│   ├── login-flow.ts<br>│   └── checkout-flow.ts<br>│<br>├── assets/                  ← # 模板（Claude 可直接 copy）<br>    ├──test-template.ts<br>    └── report-template.md</pre><p>可以注意上面的範例中，assets 裡面存放了「模板」類型的檔案，這些檔案能讓 agent 依照我們期望的格式進行「照抄」，確保文件內容維持一致性。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JBkuTk4-ISLsMhvSMXfcqw.jpeg" /><figcaption>SKILL.md 作為入口文件，用來說明整體框架與使用方式</figcaption></figure><h3>Avoid Railroading Claude</h3><blockquote>避免過度規範</blockquote><p>剛開始在學習使用 agent 時，我們時有耳聞「應該清楚地告訴 agent 每一步該怎麼做」，然而這種「步驟式」的說明現在反而對於 agent 來說是一把雙面刃，好處是「agent 基本上會照著指示實作」，壞處卻是「agent 會因為這些過於明確的指示，而無法依照多變的情境進行不同的處理」。</p><p>Agent 現在聰明的可以，我們只要給予必要的資訊，然後提供足夠的操作彈性，讓 agent 自動判斷該該種情境對應的處理方式。</p><p>以 Git 操作的 skill 為例：</p><h4>過度規範的寫法</h4><ol><li>執行 git log 查找 commit</li><li>執行 git cherry-pick &lt;hash&gt;</li><li>如果有衝突，執行 git status 查看狀況</li><li>打開並查看每個衝突的檔案</li><li>針對每個衝突，選擇保留版本、修改內容或跳過</li></ol><p>（寫完每個步驟⋯⋯）</p><h4>合適的寫法</h4><ul><li>在乾淨的分支上進行 cherry-pick 並處理衝突</li><li>請確保原始目的與邏輯，如果無法安全合併，請說明原因</li></ul><h3>Think through the Setup</h3><blockquote>思考所需的前置資訊</blockquote><p>如果我們要寫一個「天氣資訊」相關的 skill，你覺得 agent 在使用這個 skill 前，應該要先向我們確認哪些資訊，才能有效地回答呢？</p><p>至少 agent 需要知道「城市」、「日期」這兩件事，才能進一步去查詢並提供對我們有用的天氣資訊吧！</p><p>因此有些 skill 在 agent 使用前，會需要從指定的 config 檔案中查看是否有相關設定，這些必要的設定會建議存放在 skill 底下的 config.json 中。</p><p>如果沒有的話，則可以指示 agent 使用 AskUserQuestion 工具，向使用者詢問資訊，再繼續進行操作。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*LM8C1bAMJrQf7eJA-yjZ2A.jpeg" /><figcaption>說明使用方式以及如何取得前置資訊</figcaption></figure><h3>The Description Field Is For the Model</h3><blockquote>描述觸發條件</blockquote><p>在寫 SKILL.md 時，我們會以為 description 是用來敘述這個 skill 的功能與使用方式，然而 description 的真正作用是用來「描述這個 skill 的觸發條件」，讓 agent 知道什麼時候該使用這個 skill。</p><p>因為當 Claude Code 開始一個新的對話 session 時，它會先載入所有可用的 skills 以及對應的 description，如果使用者在對話過程中，提到了符合 description 中所描述的條件，agent 就會自動觸發該 skill 來完成對應的任務。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*C_7iaQ7hTlX_EQh6ttROCQ.jpeg" /><figcaption>相較於左圖，右圖的 description 是更符合 skills 的「觸發條件描述」</figcaption></figure><h3>Memory &amp; Storing Data</h3><blockquote>給予記憶能力</blockquote><p>受限於上下文（context）長度限制，通常每當我們跟 Claude Code 進行一段對話並一些任務後，要不就使用 /compact 來壓縮與總結先前的對話內容，要不就是用 /new 來開啟一輪新的對話 session，無論哪種方式都會導致先前對話內容的遺失，進而影響到後面的任務執行。</p><p>針對那些需要「前情提要」的 skills，我們可以透過 .log 或是 .json 來存儲對話過程中所產生的資料摘要，如果有必要，甚至可以使用 SQLite 資料庫來更有系統地儲存資料。</p><p>官方也有提醒，有時候存放在 skill 底下的 data 可能會因為「升級 skill」時被刪除，所以建議存在 ${CLAUDE_PLUGIN_DATA} 所指向的路徑，確保資料不會因為升級而遺失。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*2Q-AAearM7ri3tSHdjCu5A.jpeg" /><figcaption>透過 SKILL.md 的 memory 區塊讓 agent 知道如何存放每次立會紀錄</figcaption></figure><blockquote><em>${CLAUDE_PLUGIN_DATA} 是對應每個 plugin 所提供存放 data 的路徑。</em></blockquote><blockquote><em>例如 plugin 的名稱叫作 </em><em>formatter@my-marketplace，那 </em><em>${CLAUDE_PLUGIN_DATA} 則會對應到 </em><em>~/.claude/plugins/data/formatter-my-marketplace。</em></blockquote><blockquote><em>詳細的轉換規則可參考 </em><a href="https://code.claude.com/docs/en/plugins-reference?utm_source=chatgpt.com"><em>Plugins reference — Persistent data directory</em></a><em>。</em></blockquote><h3>Store Scripts &amp; Generate Code</h3><blockquote>提供可重用的函式</blockquote><p>前面有稍稍提到，我們可以在 asset 中存放樣板文件，讓 agent 根據規範產出風格一致的文件，省去 agent 每次從零做起的時間，更可以減少 token 的消耗！</p><p>依循這個理念，我們也可以先在 skills 定義好一些常用的函式（helper functions），讓 agent 可以直接在對應情境調用指定的函式。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*knWnHnhpKGwPTuSkKcZLLQ.jpeg" /><figcaption>定義常用的資料搜尋方法</figcaption></figure><p>Agent 除了能調用這些函式，甚至可以自行將這些函式進行排列組合，來完成更複雜的任務。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ozI-yZkAHv30h6qJGih83w.jpeg" /><figcaption>Agent 可以用前面預先定義好的方法，自行做出一個更複雜的 investigate.py</figcaption></figure><h3>On Demand Hooks</h3><blockquote>特定需求功能</blockquote><p>偶爾會聽到網路上有些人抱怨「AI 把我的東西全部刪掉了」，這到底是 AI 的反撲還是我們給予 AI 過大的權限？又或者是我們描述地不夠清楚，導致 AI 會錯意，才發生了這樣的慘劇呢？</p><p>無論是哪種情況，說穿了，我們想要的就是特定狀況下不要「刪除檔案」或是「做出毀滅性的操作」。</p><p>舉例來說，我們可以定義一個名為 /careful 的 skill：</p><pre>blocks rm -rf, DROP TABLE, force-push, kubectl delete via PreToolUse matcher on Bash.</pre><p>一旦我們使用在對話過程中使用了 /careful，agent 在當前的 session 便會遵循的這個 skill 所描述的行為，避免進行一些可能導致破壞的操作。</p><p>要注意的是，這些指令通常有適合的使用時機，如果在不當的時機使用，像是需要進行一些不必要的檔案刪除時，就會因為 /careful 過度限制而導致無法正常完成任務。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*smx0iX4ffgz42q_VQS9pzA.jpeg" /><figcaption>撰寫 skills 應該注意的事情</figcaption></figure><p>對於新手工程師而言，使用現成的 skills 像是一把雙面刃，誠然 skills 賦予 agent 更強大的能力，但也剝奪了我們在手動操作中會學習的經驗，以及對應各種情境應該要使用的 debug 方法。</p><p>在這個越來越少「純手工寫程式」的 AI 世代，我們至少可以看看別人是怎麼寫 skills，然後按照自己的需求、知識，改寫出符合自己風格的 skills，奪回一些自主思考的能力。</p><p>如果喜歡這篇文章：</p><ul><li>可以給我一個掌聲，並且追蹤我的 <a href="https://medium.com/@chienchuanwang">Medium</a> 與 <a href="https://github.com/chienchuanw">GitHub</a>！</li><li>歡迎在文章下方留言分享你的經驗或想法，我們一起進步！</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4ce4e07f959d" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Claude 工程師教你怎麼用 skills：怎麼好好分類 skills]]></title>
            <link>https://medium.com/@chienchuanwang/claude-%E5%B7%A5%E7%A8%8B%E5%B8%AB%E6%95%99%E4%BD%A0%E6%80%8E%E9%BA%BC%E7%94%A8-skills-%E6%80%8E%E5%80%91%E5%A5%BD%E5%A5%BD%E5%88%86%E9%A1%9E-skills-1391d7f5701f?source=rss-8169ac429c8c------2</link>
            <guid isPermaLink="false">https://medium.com/p/1391d7f5701f</guid>
            <category><![CDATA[claude-code]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[skills]]></category>
            <category><![CDATA[programming]]></category>
            <dc:creator><![CDATA[Chuan 建權]]></dc:creator>
            <pubDate>Thu, 26 Mar 2026 16:00:43 GMT</pubDate>
            <atom:updated>2026-03-28T09:29:21.012Z</atom:updated>
            <content:encoded><![CDATA[<p>Skills 襲捲整個軟體業已經不是一兩天的事，自從 skills 的出現，我們把本來對於 MCP 的狂熱，轉移到處處搜刮別人推薦的 skills，俗話說「技多不壓身」，那 skills 是不是也是多多益善呢？</p><h3>什麼是 skills</h3><p>剛開始轉移到 skills 時，我對於 skills 的刻板印象還停留在 .md 的文件檔，想說這不就是把常用的 prompt 文件化，減去重複輸入類似指令的麻煩？</p><p>然而 markdown 僅僅是 skills 的一小部分，skills 的資料夾內還可以包含 scripts、assets、data 等多類型的檔案，讓後續 agent 在操作時，可以進行更複雜的運用。</p><p>官方也推薦了這三份文件，作為學習 skills 的入門：</p><ul><li><a href="https://anthropic.skilljar.com/introduction-to-agent-skills">Introduction to agent skills</a></li><li><a href="https://code.claude.com/docs/en/skills#frontmatter-reference">Extend Claude with skills</a></li><li><a href="https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills">Improving skill-creator: Test, measure, and refine Agent Skills</a></li></ul><h3>Skills 有哪些種類</h3><p>隨著我們收集（搜刮？）的 skills 越來越多，不僅 skills 的資料夾變得越來越龐雜，來自各方的 skills 也可能相互重複，這時我們會需要一套分類系統，來整歸放這些 skills，雖然官方沒有硬性的分類方式，但會建議「一個 skills 只存放在一個種類資料夾內」。</p><p>Claude 工程師 Thariq 也在 <a href="https://x.com/trq212/article/2033949937936085378">Lessons from Building Claude Code: How We Use Skills</a> 一文中，提供下面幾種類別的分類方式，讓毫無頭緒的 P 人們，可以有個初步整理概念：</p><h4>Library &amp; API Reference</h4><p>用於教導 Claude Code 如何正確使用套件、函式庫、CLI、SDK 等，避免他們在操作上亂用或是使用錯誤的版本。</p><p>通常這些 skills 裡面也會方一些參考用的程式代碼片段（reference code snippets），以及常見的錯誤（gotchas）與對應的解法，讓 agents 可以避開這些地雷。</p><ul><li>極端案例（edge case）、容易踩雷的狀況</li><li>每一個指令的案例與使用情境</li><li>設計系統的規劃</li></ul><h4>Product Verification</h4><p>用於驗證 agent 所產出的結果是否和預期的，也因為要有一個能對照的結果，通常會搭配 playwright、tmux 這類可以操作瀏覽器、終端機的套件，來模擬人類的行為，確認最終的結果是否正確。</p><p>我們甚至可以透過 skill 裡面預先寫好的 script，讓 agent 將結果進行錄影或是進行斷言驗證，確保最終的結果正確無誤。</p><ul><li>除了跑測試，也需要定義功能流程的成功標準，讓 agent 可以在每個步驟進行驗證</li><li>不單是 UI 上的操作，同時也要確認狀態的轉換是否正確</li><li>讓 agent 可以模擬 CLI input 並讀取對應的 output</li></ul><h4>Data &amp; Analysis</h4><p>讓 agent 可以連接資料庫與類似 Grafana 的監控工具，並且提供資料庫的操作方法進而取得資料，並且進行分析與處理資料。</p><h4>Business Automation</h4><p>這邊只要放置那些將「重複性作業」化為單一指令的 skills，這些 skills 本身看起來其實不複雜，更像是一連串簡單的操作步驟，但操作的過程中有可能會需要倚賴其他的套件與 MCP，像是：「將先前的輸出結果存為 log 檔案留存」等。</p><h4>Scaffolding &amp; Templating</h4><p>這類型的 skills 通常用於快速建立模板或框架，通常這些 skills 中會搭配 scripts 協助使用者建立與設定專案，而這些 skills 存在的意義，也是為了滿足我們在開發過程中，有一些需求與其用程式碼說明，用熟悉的自然語言說明會來得更為輕鬆。</p><h4>Code Quality &amp; Review</h4><p>相較於每位工程師對於程式審查的標準各不相同，透過 skills 可以將團隊審查的內容、方向標準化，像是有些工程師會將程式碼審查的工作交付給多個 sub-agent，讓他們彼此相互檢查、討論，直到重大問題都解決。這通常也會搭配一些 scripts 或是 lint 工具進行 code-style 驗證，我們甚至可以把這些 skills 改造成 hook 或是 GitHub Actions 的其中一環。</p><h4>CI/CD &amp; Deployment</h4><p>主要用於 fetch、push、deploy 等部署更新的 skills，這些 skills 有時候也包含了搜集部署過程中的訊息，以便解決其中發生的錯誤。</p><h4>Incident Runbooks</h4><p>像我們做筆記一樣，這類型的 skills 主要用於記錄各式錯誤與狀況，並透過跨系統、多工具的方式進行排查，然後產出一份清晰明確的診斷紀錄，這份紀錄不僅說明了錯誤原因、影響範圍、建議的修復方式，甚至也可以給未來遇到類似錯誤時，作為參考資料。</p><h4>Infrastructure Ops</h4><p>這類型的 skills 主要用於日常維運的操作，其中通常會對一些破壞性的操作設下防護限制，一方面可以減輕工程師的負擔，另一方面也可以避免因為操作錯誤導致的災難性後果。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*IxZLWOdHT_xvH7dkVDE5Vw.jpeg" /><figcaption>Claude 工程師推薦的分類方式</figcaption></figure><p>根據這些分類方式，其實隱隱約約能感受到，這就像依照軟體開發的進程，把工程師平常工作內容與學習的技能進行切分，而如果把這邊的每一個類別各用一句表示：</p><ol><li>如何做事情並且把事情做對</li><li>判斷哪些事情有價值</li><li>哪些事情需要再優化</li><li>把例行公事、重複性的任務變得標準化、自動化</li><li>將最佳實踐（best practices）固化為模板，維持一致的品質</li><li>進行審查與修正，確保程式碼的正確與質量</li><li>將程式安全部署上線</li><li>紀錄 debug 經驗並記取教訓</li><li>進行日常維運管理</li></ol><p>在運用 AI 進行開發的進程裡，從最初我們只是把 AI 當作迅速找尋答案的工具，省去我們自己在 StackOverflow 爬文，到嫁接 MCP 允許 AI 能夠透過協議介面，以自然語言操作特定軟體，到現在我們像是「打造一個 AI 工程師」。</p><p>這種旅程裡，我們可以清楚感受到自己「手寫」的程式碼變少許多，然而對於知識的需求與焦慮卻是翻倍增加，感覺每一種技術我們都需要了解其原理，知道怎麼搭配才能最有效率地解決問題，我們像是從本來只需要精通一種風格的廚師，變成要熟稔各種食材組合的主廚，有種每天都有東西要認識，雖然苦痛卻也很興奮。</p><p>如果喜歡這篇文章：</p><ul><li>可以給我一個掌聲，並且追蹤我的 <a href="https://medium.com/@chienchuanwang">Medium</a> 與 <a href="https://github.com/chienchuanw">GitHub</a>！</li><li>歡迎在文章下方留言分享你的經驗或想法，我們一起進步！</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1391d7f5701f" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[光擬什麼事：fader 上面放什麼 CP 值最高？]]></title>
            <link>https://medium.com/@chienchuanwang/%E5%85%89%E6%93%AC%E4%BB%80%E9%BA%BC%E4%BA%8B-fader-%E4%B8%8A%E9%9D%A2%E6%94%BE%E4%BB%80%E9%BA%BC-cp-%E5%80%BC%E6%9C%80%E9%AB%98-8485cc2607ff?source=rss-8169ac429c8c------2</link>
            <guid isPermaLink="false">https://medium.com/p/8485cc2607ff</guid>
            <category><![CDATA[lighting]]></category>
            <category><![CDATA[ma2]]></category>
            <category><![CDATA[lighting-design]]></category>
            <category><![CDATA[concert-lighting]]></category>
            <category><![CDATA[grandma2]]></category>
            <dc:creator><![CDATA[Chuan 建權]]></dc:creator>
            <pubDate>Mon, 23 Mar 2026 14:29:38 GMT</pubDate>
            <atom:updated>2026-03-23T14:29:38.645Z</atom:updated>
            <content:encoded><![CDATA[<p>這幾天在 reddit 的 grandMA2 看到一篇發文，是一位 MA2 初學者的提問：「我有一台 grandMA2 onPC CMDWing，fader 主要控制光束燈移動、煙量大小；button 部分則用來控制燈光亮暗與閃爍效果，這樣的分配方式合理嗎？」</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/760/1*ByNGF3yblcEfoLEjZZJ9OQ.png" /><figcaption><a href="https://www.reddit.com/r/grandMA2/comments/1rydaao/what_do_you_guys_put_on_the_faders/"><em>What do you guys put on the faders?</em></a><em><br> by </em><a href="https://www.reddit.com/user/After-Ad-9452/"><em>u/After-Ad-9452</em></a><em> in </em><a href="https://www.reddit.com/r/grandMA2/"><em>grandMA2</em></a></figcaption></figure><p>相較於 Avolites 系列控台隨隨便便一頁都有 10–20 隻 fader，grandMA2 的 CMDWing 只有 6 隻 fader 與 button，就算加上了 FaderWing 也只是再多 15 隻 fader，不要聽起來 21 隻好像很多，但用來面對現場各種臨時狀況，真的會想咒罵一句：「MA 的，難道就不能再多幾隻 fader 嗎？」</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/500/1*VXO2sxZM_Q4TM0NMD1fokA.png" /><figcaption><em>Avolites Pearl Expert 一頁有 20 隻 fader 再加上常設的 60 fader，簡直了！</em></figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*b4zMsxOD1AskcvpjFhaiXg.png" /><figcaption><em>grandMA2 的 CMDWing（右邊）只有 6 隻 fader，再加上 FaderWing（左邊）也才多 15 隻 fader⋯⋯</em></figcaption></figure><p>有的人認為應該要將 Speed Master、Group Master 這類需要微調數值的功能放在 fader 上，也有人認為應該要設定成 zoom、frost 的參數，用 fader 來調節 zoom、frost 該大該小，十個燈光師大概有八種答案。</p><p>貼文中有則回覆引起了我的注意，有位網友分享了知名燈光設計 Nook Schoenfeld 在 2007 寫的文章〈<a href="https://plsn.com/articles/technopolis/the-ultimate-punt-page-1/">The Ultimate Punt Page</a>〉，文內講述了 Nook 是如何配置自己的控台設定，來應對電視節目、演唱會、商業活動等不同性質的演出。</p><blockquote>這篇文章寫於 2007 年，當時的 MA2 尚未發行，但 Nook 對於控台設定的思考，對於我們今天的討論仍有很大的參考價值。</blockquote><p>作為一位熱愛即時操作（busking）的燈光設計，Nook 在文章的開頭便提到 — — 「<strong>越多的 fader 與 button 越好</strong>」，同時他也喜歡 wing（附加控台）的概念，因為他是透過 wing 來區分不同的燈具，例如傳統燈放一區，電腦燈則放在另外一區。</p><blockquote>The more faders and executor buttons on a console, the better. <br>— Nook Schoenfeld</blockquote><p>不管每個人的偏好如何，這其實是在考驗「<strong>燈光師對於有限 fader 與 button 的資源管理</strong>」，而背後通常會考慮：</p><ul><li>演出的性質是否很即興</li><li>燈光師對於 MA 控台的熟悉程度</li></ul><p>當一個演出性質越偏向即興，也就越考驗燈光師的臨場反應，而實體控台作為燈光師最直覺地操作介面，應該將 fader 與 button 設定為那些時常用到、需要進行微操作的內容。</p><p>其中 fader 主要用於需要調節速度、數值大小的內容，像是面光的數值、effect 的速度；而 button 則著重於「狀態、效果的切換」，像是頻閃效果的開關、有無稜鏡等。</p><p>另外當燈光師對於控台愈加熟悉，會知道怎麼樣自定義每一顆 fader 與 button 的功能，又有哪些效果其實可以直接打指令、點選的方式來操作，甚至是在觸控螢幕上另外創建虛擬 fader，而不是一定要佔用有限實體的 fader 與 button。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/928/1*OfstcnZL5pN46RQvHcICVw.png" /><figcaption><em>MA2 控台分成上半部的 fader 區塊與下半部的 button 區塊，而這裡的每一個鍵都可以由燈光師自行定義其功能。</em></figcaption></figure><p>那些需要立即反應過來的事件，像是面光的亮暗會直接影響觀眾的視覺感受，理應靠著我們的肌肉記憶反射性地去操控；而那些稍微可以等待的事件，像是煙霧的量，因為觀眾對於煙霧的感受沒有那麼敏感，就可以透過虛擬 fader 來慢慢調整，而不是一定要實體 fader。</p><p>隨著燈光師對 MA 控台的熟悉以及現場經驗的累積，慢慢會在心中建立其一個排序，而這個排序其實就是「突發事件允許的反應時間」。</p><p>之後我們再來聊聊燈光即時操作 busking 的細節與觀念吧！</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/400/1*ktBAsuXrAARziy213JcplQ.jpeg" /><figcaption>🥹：我只是想要多兩頁 💻：去你 MA</figcaption></figure><p>如果喜歡這篇文章：</p><p>可以給我一個掌聲，並且追蹤我的 <a href="https://www.instagram.com/chienchuanw">Instagram</a> 與 <a href="https://medium.com/@chienchuanwang">Medium</a>！</p><p>也歡迎在文章下方留言分享你的經驗或想法，我們一起進步！</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8485cc2607ff" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[光擬什麼事：如何使用 MIB 讓燈具在黑暗中先就定位]]></title>
            <link>https://medium.com/@chienchuanwang/%E5%85%89%E6%93%AC%E4%BB%80%E9%BA%BC%E4%BA%8B-%E5%A6%82%E4%BD%95%E4%BD%BF%E7%94%A8-mib-%E8%AE%93%E7%87%88%E5%85%B7%E5%9C%A8%E9%BB%91%E6%9A%97%E4%B8%AD%E5%85%88%E5%B0%B1%E5%AE%9A%E4%BD%8D-ff6dbd7c76d1?source=rss-8169ac429c8c------2</link>
            <guid isPermaLink="false">https://medium.com/p/ff6dbd7c76d1</guid>
            <category><![CDATA[ma2]]></category>
            <category><![CDATA[grandma2]]></category>
            <category><![CDATA[lighting-design]]></category>
            <category><![CDATA[lighting]]></category>
            <category><![CDATA[concert-lighting]]></category>
            <dc:creator><![CDATA[Chuan 建權]]></dc:creator>
            <pubDate>Sun, 22 Mar 2026 18:28:34 GMT</pubDate>
            <atom:updated>2026-03-23T12:46:44.645Z</atom:updated>
            <content:encoded><![CDATA[<p>在演唱會中偶爾會看到某一顆燈，它第一次亮起來是照在主唱身上，中間間奏時因為暫時不需要而被關掉，等到下次再次亮起時，本應該直接照亮正在 solo 的吉他手，卻看到這顆燈越來越亮的同時，才慢悠悠地從主唱移動到吉他手的位置。</p><p>如果這個移動的過程，的確是你想要的效果，恭喜你，可以不用看接下來的文章了！</p><p>如果你希望能讓燈具在黑暗中，預先改變至指定的位置或狀態，那這個 MIB 功能就會是你所需要的。</p><h3>MIB 是什麼</h3><p>MIB (Move in Black) 顧名思義是「在黑暗中移動」，可以想像成一位演員，在舞台上 spotlight 未亮時，他先偷偷地在黑暗中走到指定的位置， spotlight 一亮，他就已經站在正確的位置上了，而不是 spotlight 一亮他才開始走位，那樣多尷尬。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/299/1*nG8LicjtVcINsuCKoQBoUQ.jpeg" /><figcaption>打錯人啦！</figcaption></figure><p>我們先來看看實例：</p><pre># cue 1<br>Fixture 1 亮起，打在主唱身上<br><br># cue 2<br>Fixture 1 暗掉<br><br># cue 3<br>Fixture 1 亮起，打在吉他手身上</pre><p>想像一下，執行 cue 3 時，Fixture 1 會是怎麼樣移動呢？</p><p>正常來說應該是「Fixture 1 在亮起的同時，也緩緩地從主唱身上移動到吉他手身上」，我們會很清楚（很尷尬）地看到 Fixture 1 的位移過程。</p><p>如果可以，我們應該會更希望 Fixture 1 能在未亮時，就先偷偷地走到吉他手的位置，等到 Fixture 1 亮起來，就可以直接打亮吉他手。</p><p>因此我們可以在 grandMA2 進行 MIB 的設定，讓燈具在未亮起狀態下，預先變色與移動到指定的狀態，等到燈光亮起，馬上看到燈具在指定的位置顯示正確的顏色，而不是看到燈光慢慢變色、慢慢移動，進而影響整體的設計的細節。</p><p>至於燈具是否能進行 MIB ，MA 是根據 dimmer 的 intensity 亮度來判斷，也就是這個燈具在在走到亮起（intensity 亮度大於 0 ）的 cue 前，是否有黑暗的時刻可以進行 MIB，如果可以，我們在「燈具亮起的 cue」看見 MIB 的欄位顯示 * 的星號，提醒設計師這個 cue 是可以進行「有效的 MIB」設定。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/822/1*WlUuxchfHVcXv34XZ40_nA.png" /><figcaption><em>MIB 的星號 * 提示</em></figcaption></figure><blockquote>比較可惜的是，MA 只能提醒「這個 cue 有燈具可以 MIB」，但沒辦法清楚告訴你「哪個燈具可以 MIB」。</blockquote><h3>MIB 的設定</h3><p>當你對 MIB 的格子進行右鍵點擊後，會跳出 Select MIB 的彈出視窗，讓設計師決定應該以哪種方式進行 MIB。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/822/1*6VQW2bIPFhl3I1KX3Q1cUA.png" /><figcaption>右鍵點選 MIB 欄位後顯示的 Select MIB 彈出視窗</figcaption></figure><ul><li>None：不進行 MIB，燈具會按照預設的方式變換到指定狀態。</li><li>Late：會盡可能在「最後一刻」才進行 MIB，但一定會在燈具亮起前完成 MIB。</li><li>Early：會盡可能在「儘早」進行 MIB，也就是 MA 一判定可以 MIB 時，直接進行 MIB。</li><li>Cue #：會在使用者指定的 cue 進行 MIB，如果 MA 判讀該 cue 無法進行 MIB，則會在「指定 cue 後的最早的時間點」進行 MIB。</li></ul><blockquote><em>如果選擇 MIB 模式後呈現「紅字」，代表該 cue 目前沒有可以進行 MIB 的燈具。</em></blockquote><h3>什麼時候該用哪種 MIB</h3><p>就我個人而言，會偏好使用 Early 作為預設的 MIB 模式，因為這樣可以讓燈具在黑暗中盡可能早地就位，燈具一亮通常也會是正確的狀態，但這不代表所有情況都適合無腦使用 MIB 或是 Early 模式，下面各舉一些例子來說明。</p><h4>None</h4><p>既然會選擇 None 就代表我們希望「這個動作能被看到」，像是有的時候我們會希望透過燈具的拉抬（tilt up）來表現光的上升感，藉此讓觀眾感到澎湃，那這個時候我們會刻意不進行 MIB，讓燈具在亮起時，也能看到它上升的過程。</p><h4>Late</h4><p>MIB 裡的 Black 預設的是一個「理想的全黑」空間，可是受限於演出場地的物理條件，觀眾或許還是能看見燈具在「黑暗中」的狀態，所以當使用 Early 時，燈具提早改變狀態的過程可能會影響觀眾的視覺感受，像是明明燈沒亮，卻一直在左右移動，這時我們可以改用 Late，讓燈具在最後一刻才進行 MIB，盡可能減少對觀眾的視覺干擾。</p><h4>指定 Cue</h4><p>跟 Late 類似，我們也可以指定在某個特定的時間點進行 MIB，這個時間點可能對於觀眾的視覺影響是最小的，所以我們指定燈具在該時間點進行 MIB。</p><h3>MIB 的硬限制</h3><p>由於 MA 的 MIB 是以「cue」為單位進行，也就是說如果將 cue 5 設定為 MIB 為 Early，不管有多少燈具、哪些燈具，只要是 MA 判定可以進行 MIB 的，會「全部」一起進行 MIB，而無法單獨對單一的燈具進行 MIB 設定。</p><p>另一個硬限制則是來自於「燈具本身的物理限制」，當燈具從 A 點移動到 B 點，移動速度會因為受限於本體的重量與機體設計，再怎麼快也不可能零秒完成移動，此時如果前面預留 MIB 的時間不足，即便 MA 判定可以 MIB，但還是會發生燈具亮起時，仍在進行位移的窘況。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/743/1*vgBKuCEE7yKaUneJAySMVA.jpeg" /><figcaption>希望燈具 MIB → 燈具開始 MIB → 來不及 MIB → (OДO)</figcaption></figure><p>如果喜歡這篇文章：</p><ul><li>可以給我一個掌聲，並且追蹤我的 <a href="https://medium.com/@chienchuanwang">Medium</a> 與 <a href="https://github.com/chienchuanw">GitHub</a>！</li><li>歡迎在文章下方留言分享你的經驗或想法，我們一起進步！</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ff6dbd7c76d1" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[順便學 Ruby：controllers spec 與 requests spec 有什麼差別？]]></title>
            <link>https://medium.com/@chienchuanwang/%E9%A0%86%E4%BE%BF%E5%AD%B8-ruby-controllers-spec-%E8%88%87-requests-spec-%E6%9C%89%E4%BB%80%E9%BA%BC%E5%B7%AE%E5%88%A5-095b1b424040?source=rss-8169ac429c8c------2</link>
            <guid isPermaLink="false">https://medium.com/p/095b1b424040</guid>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[ruby-on-rails]]></category>
            <category><![CDATA[testing]]></category>
            <category><![CDATA[web-development]]></category>
            <category><![CDATA[programming]]></category>
            <dc:creator><![CDATA[Chuan 建權]]></dc:creator>
            <pubDate>Tue, 30 Dec 2025 09:02:26 GMT</pubDate>
            <atom:updated>2025-12-30T09:02:26.463Z</atom:updated>
            <content:encoded><![CDATA[<p>初次進行 Rails 開發與撰寫 Rspec 測試時，會想說既然有 controllers，那測試裡有對應的 controllers spec 測試也是理所當然吧。</p><p>沒想到 Rspec 官方卻是這麼說的：</p><blockquote><em>For new Rails apps: we don’t recommend adding the rails-controller-testing gem to your application. The official recommendation of the Rails team and the RSpec core team is to write request specs instead. Request specs allow you to focus on a single controller action, but unlike controller tests involve the router, the middleware stack, and both rack requests and responses. This adds realism to the test that you are writing, and helps avoid many of the issues that are common in controller specs.</em></blockquote><p>簡單來說，Rails 官方認為比起 controllers specs，使用 requests specs 測試能夠更完整地模擬實際的請求過程。</p><h3>controllers vs requests</h3><p>那到底 controllers 與 requests 有什麼差別呢？</p><p>想像 Rails app 是一家餐廳：</p><ul><li>Controller 像是廚師：負責處理特定菜（action），比如煎一個排骨。</li><li>整個 Request 就像是顧客點餐進來的一整個流程：點菜、送單、廚房處理、出餐、上桌。</li></ul><h3>controllers spec 的比喻</h3><p>Controller spec 像把廚師單獨放在實驗室裡，只讓他對一種食材做菜，不管客人怎麼點餐、也不經過餐廳的流程。你可能會問：「當我告訴廚師煎排骨時，他有沒有回傳 OK?」</p><p>這種測試只關心「廚師做菜邏輯本身」，顯而易見的缺點是：你沒測到真實點餐流程中的路由、middleware、參數驗證等整個機制。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/500/1*5fFw_rC0oi2W6bmVLaX4TQ.jpeg" /><figcaption>controllers spec 比較接近單元測試</figcaption></figure><h3>requests spec 的比喻</h3><p>Request spec 是直接從顧客（HTTP 請求） 的角度測試整個流程。</p><p>你會問：「我從餐廳的點餐端送出請求，整個流程（route、middleware、controller、response）到底有沒有正常？response 長什麼樣子？」</p><p>這是一個完整的 HTTP request → Rails stack → HTTP response 的過程，它比只是測 controller 邏輯更貼近系統實際運作。</p><p>因此從 RSpec 官方與 Rails 團隊的立場來看，新的 Rails 專案不建議再加入 rails-controller-testing gem，也不鼓勵 controller specs，而是建議改用 request specs，因為 request specs 可以不僅可以測試單一 action，它也會跑 routing、middleware 與 Rack request/response，加強測試的「真實性」，基本上也覆蓋 controller specs 的測試需求。</p><h3>實際範例</h3><p>假設我們有一個 UsersController：</p><pre># app/controllers/users_controller.rb<br>class UsersController &lt; ApplicationController<br>  def index<br>    @users = User.all<br>    render json: @users<br>  end<br>end</pre><h3>如果是 controllers spec</h3><pre># spec/controllers/users_controller_spec.rb<br>RSpec.describe UsersController, type: :controller do<br>  it &quot;回傳 200 OK&quot; do<br>    get :index<br>    expect(response).to have_http_status(:ok)<br>  end<br>end</pre><p>這段測試：</p><ul><li>直接呼叫 controller action get :index，但不走 routes 也不經過 middleware。</li><li>只是在確認 controller 在隔離環境下是否有產生 200 回應。</li><li>這不是一個完整的 HTTP 請求流程，只是測「這個方法被呼叫後的結果」。</li></ul><p>缺點：</p><ul><li>路由錯誤不會被抓到（因為你直接呼叫 action）。</li><li>middleware 驗證、參數解析、session 都會被跳過。</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*o-C6DkS2-rdK0vDRa73r9A.png" /><figcaption>很有可能 controllers spec 測試過了，但實際上在 requests 過程中還有其他的問題</figcaption></figure><h3>如果是 requests spec</h3><pre># spec/requests/users_spec.rb<br>RSpec.describe &quot;Users API&quot;, type: :request do<br>  describe &quot;GET /users&quot; do<br>    it &quot;回傳 200 OK 並取得使用者列表&quot; do<br>      get &quot;/users&quot;<br>      expect(response).to have_http_status(:ok)<br>      expect(response.body).to include(&quot;users&quot;)<br>    end<br>  end<br>end</pre><p>這段測試真的發出一個 HTTP GET /users 請求，並走過：</p><ol><li>Routing → 確認 /users 有成功對到 controller 路徑</li><li>Middleware → 例如 session、認證、parser 等</li><li>Controller Action → 真正進到 UsersController#index</li><li>Response Body / HTTP 狀態 → 我們能檢查回傳內容是什麼</li></ol><h3>那我們還會需要 controllers spec 嗎？</h3><p>以新的 Rails 專案而言，雖然不建議，但某些極端情況有人仍用 controller specs：</p><ul><li>對舊專案「大量舊的 controller specs」還沒重寫完之前保留。</li><li>想極端 isolation 測 controller 方法本身（但這種情況更推薦把邏輯抽到 service/poro 裡再寫 unit test）。</li></ul><p>但對新專案來說，基本上不需要 controller specs 了，request specs 幾乎能完全取代它。</p><p>因為 request specs 更真實地模擬了 完整的 HTTP 請求流程（包含 routing、middleware、Rack stack），能更貼近實際使用者與 API 交互的情境。</p><p>這種測試方式不僅能驗證單一 action 的回應，也能捕捉到跨層級的錯誤與行為不一致，而不是只測 controller 方法的 isolated result。</p><p>Rails 與 RSpec 核心團隊在 Rails 5+ 與 RSpec 3.5+ 之後都<strong>不再推薦使用 controller specs</strong>，而是建議用 request specs 作為主要測試策略，它能提供更高的測試真實性與可靠性，並避免 controller specs 常見的假設與盲點。</p><p>如果喜歡這篇文章：</p><ul><li>可以給我一個掌聲，並且追蹤我的 <a href="https://medium.com/@chienchuanwang">Medium</a>！</li><li>歡迎在文章下方留言分享你的經驗或想法，我們一起進步！</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=095b1b424040" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[觀念筆記：從 Race Condition 到無鎖設計]]></title>
            <link>https://medium.com/@chienchuanwang/%E8%A7%80%E5%BF%B5%E7%AD%86%E8%A8%98-%E5%BE%9E-race-condition-%E5%88%B0%E7%84%A1%E9%8E%96%E8%A8%AD%E8%A8%88-19d6ea1a4801?source=rss-8169ac429c8c------2</link>
            <guid isPermaLink="false">https://medium.com/p/19d6ea1a4801</guid>
            <category><![CDATA[web-development]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[system-design-concepts]]></category>
            <category><![CDATA[race-condition]]></category>
            <category><![CDATA[backend-development]]></category>
            <dc:creator><![CDATA[Chuan 建權]]></dc:creator>
            <pubDate>Wed, 17 Dec 2025 11:39:33 GMT</pubDate>
            <atom:updated>2025-12-17T11:39:33.804Z</atom:updated>
            <content:encoded><![CDATA[<p>在設計多層級的電商系統時，必然會遇到多個使用者同時編輯同一件商品的狀況，當我們送出更新時，到底該以哪位使用者送出的請求作為最後的結果呢？</p><p>我們可以先想想看，這個情境：</p><ul><li>使用者 A 正在編輯商品 A，並且將價格改為 100 元。</li><li>使用者 B 正在編輯商品 A，並且將價格改為 200 元。</li><li>使用者 B 先完成編輯，並且將價格更新為 100 元。</li></ul><p>在兩位使用者沒有互相溝通的前提下，如果此時使用者 A 也送出更新，那麼我們預期的結果是：</p><ol><li>價格應該要更新為 100 元。</li><li>價格應該要維持為 200 元。</li><li>系統跳出提示：在使用者 A 編輯期間，商品已被其他使用者修改，是否覆蓋？</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/798/1*SjIvblrS_whjGttDg8Mzyw.jpeg" /></figure><p>從上面這個這個情境可以帶出一個問題，也是 <strong>Race Condition 競態條件</strong>的概念：「當多個執行緒或請求同時操作同一個共享資源，最終結果取決於『執行順序』，然而這個順序本身是不可預期的，那麼系統要如何確保結果正確？」</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*a1ip0rJZV4WdJcyEqeFN2w.png" /></figure><h3>最直覺的解法：鎖（lock）</h3><p>鎖有分成多種類型，但他們的核心目的都是「同一時間，只允許一位使用者操作資源」。</p><h4>悲觀鎖 Pessimistic Lock</h4><p>悲觀鎖的思路是：「假設在大多數情況下，資源會被多個使用者同時操作，所以我們需要額外的機制來保護資源，避免發生競態條件」。</p><p>以上廁所為例，如果廁所只有一間，第一個人進去上廁所時，會把門鎖起來，直到他出來為止，這樣就可以避免第二個人進去時，第一個人還沒有出來的情況發生。</p><p>這樣的好處是絕對安全、不會發生同時使用的狀況，然而缺點也顯而易見，當前一個人遲遲不出來時，後面的人只能等待，別無他法。</p><h4>樂觀鎖 Optimistic Lock</h4><p>樂觀鎖的思路是：「假設在大多數情況下，資源不會被多個使用者同時操作，所以我們不需要額外的機制來保護資源，只需要在更新時檢查資源是否有被修改即可」。</p><p>例如有多位使用者在編輯同一份文件，系統只要在使用者提交更新時，檢查文件的版本號是否有被修改，如果版本號有被修改，則表示有其他使用者正在編輯該文件，此時可以拒絕更新，並提示使用者重新編輯。</p><p>雖然表面上看起來比起悲觀鎖有著更好的使用者體驗，然而有可能到最後檢查時才發現自己白忙一場。</p><p>除了悲觀鎖、樂觀鎖，還有另外幾種常見的鎖機制，像是分散鎖（Distributed Lock）、讀寫鎖（Read-Write Lock）、自旋鎖（Spin Lock）等，這些鎖雖然在實務操作上有些不同，但最終的目的都是為了要「保證一致性」，然而為了保證一致性卻比必須犧牲某部分的使用者。</p><h4>分散鎖 Distributed Lock</h4><p>在單機環境中，我們使用互斥鎖來保護共享資源；但在多台機器組成的分散式系統裡，本地鎖無法保護別台主機。分散鎖是延伸至整個叢集的鎖，它保證某一段時間內只有一個節點可以使用某個資源。例如複數服務同時要修改同一筆帳戶資料，必須先到「協調者」取得鎖，取得者才能進行寫入，其餘服務只能等待或放棄，這樣可以避免跨機器的競態問題。</p><p>想像有 5 家門市共享「唯一一個活動名額」。每一家門市接到客戶時，都必須先打電話給總公司確認名額是否已經被搶走，若總公司回覆「還有名額」，該門市便可以幫客戶報名；若回覆「名額已滿」，則必須告知客戶已經沒有位置。總公司就扮演分散鎖協調者的角色，確保同一時間只有一個門市可以使用這個資源。</p><h4>讀寫鎖 Read‑Write Lock</h4><p>讀寫鎖解決的是「讀多寫少」的場景。它允許多個讀者在沒有寫入者時並行讀取，當有人要寫入時，必須取得獨占鎖，此時其餘讀者與寫入者都會被阻塞，這樣可以提升讀操作的吞吐量，同時確保寫入的一致性。</p><p>想像圖書館的一本參考書。大多數人只是翻閱內容，不會更改文字，這時可以允許多人同時閱讀；但如果有老師要在書上做筆記或更新內容，他必須把書帶走並鎖上檢閱室，直到寫入完成後其他讀者才可以再次借閱，這就像讀寫鎖的行為：讀者可並行，寫者必須獨占。</p><h4>自旋鎖 Spin Lock</h4><p>自旋鎖是一種低階的鎖實作，當線程無法取得鎖時不會睡眠，而是反覆檢查鎖是否可用，直到取得為止，因為持續佔用 CPU 而不做實質工作，所以適合臨界區極短、等待時間非常短暫的情境。</p><p>像是朋友打電話佔線，你不停地撥打並聽著佔線音，直到對方掛上你才能撥通。這種「忙等」的行為就是自旋鎖；若等待時間很長，你會浪費很多時間和電力，所以大多數時候不建議使用。</p><p>那麼有沒有可能「不用鎖」呢？</p><h3>不用鎖的設計思路</h3><p>對於大多數應用來說，鎖只是防止競態的一種手段。若能透過系統設計本身來避免同時操作，不僅效能更好，也能降低實作複雜度。以下介紹幾種「不用鎖」卻能保障一致性的做法。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/278/1*7ASbW6yYs244gRtxhYe0YA.jpeg" /></figure><h4>原子操作 Atomic Operation</h4><p>原子操作指的是一個「不可分割的動作」：要麼全部完成，要麼完全不做，不會被其他執行緒看到中間狀態。 資料庫本身就提供了不可分割的原子操作。這種操作在「要嘛全做完，要嘛完全不做」的情況下執行，任一使用者只能看到操作前或操作後的完整結果，中間狀態不會曝光。</p><p>例如針對庫存的扣減可以寫成：</p><pre>UPDATE products<br>SET stock = stock - 1<br>WHERE id = 123 AND stock &gt; 0;</pre><p>透過指令可以同時檢查庫存是否大於零並扣減庫存，只要有人搶先把庫存扣光，後面的請求便不會有任何影響，完全不需要鎖。</p><p>其他類似原子操作包括：</p><ul><li>資料庫觸發器：若一次需要更新多個表，也可以利用資料庫的交易（Transaction）及觸發器機制，確保整串操作要嘛成功要嘛失敗，避免部分成功導致資料不一致。</li><li>快取系統：像 Redis 也提供 INCRBY, DECRBY, SETNX 等指令，這些都是在伺服器端一次完成，無需鎖也不會出現競態。</li></ul><p>當操作能用一條指令完成，Race Condition 根本無從發生。</p><h4>事件佇列 Queue</h4><p>另一種解法是讓「同時」變成「排隊」。把對於某資源的所有修改請求放進訊息佇列，由後端消費者依序處理，就能自然避免同時操作。</p><ul><li>實際運用：訂單入帳、庫存扣減、推送通知等需要串行化處理的場景，都可以將請求送入，並按順序處理。</li><li>優點：沒有鎖、容易水平擴充、可實現高可用。</li><li>代價：請求會有佇列延遲，並且需要考慮訊息重試與死信隊列等問題。</li></ul><p>這種模式常用於需要高吞吐的後端服務，如電商結帳、金流、訂閱通知等。</p><h4>單執行緒模型 Single Thread Model</h4><p>如果一個程式只能同時處理一個請求，自然不會出現 Race Condition。某些語言或框架就是採用這種模式：</p><ul><li>Node.js：其事件迴圈一次只處理一個事件，雖然能快速切換任務，但真正執行 JS 程式碼的時間永遠只有一條主線程，不會出現兩段程式同時修改同一個狀態。</li><li>Actor Model：如 Akka 或 Erlang，每個 Actor 都有自己的信箱，只有收信這一刻會處理訊息，其它時間不會並行執行共享狀態。</li><li>背景工作者：對單一資源採用單一消費者，例如每個商品建立一個獨立消費者或協程來處理所有對該商品的修改請求，就可以透過程式結構保證不會有兩個執行緒同時更改同一個實體。</li></ul><p>這種方式非常適合需要簡化並發邏輯的場景，但在高負載時需要透過分片或多個服務實例來分攤壓力。</p><h3>設計上的權衡</h3><p>在考慮是否採用鎖之前，可以先問自己：</p><ul><li>這個操作是否可以透過資料庫或快取提供的原子指令完成？</li><li>這個過程能否改為非同步排隊處理？</li><li>是否能把資源切分，讓每個單元由單一執行緒負責？</li></ul><p>只有在上述方法都無法滿足需求時，才需要接續考慮悲觀鎖、樂觀鎖或分散鎖等傳統同步機制。大部分成熟系統都會優先使用無鎖的設計，因為沒有鎖也意味著沒有阻塞，整體效能與可靠性都會更好，透過這樣的思路，不只可以避免 Race Condition，也能使系統更加彈性與易於維護。</p><p>如果喜歡這篇文章：</p><ul><li>可以給我一個掌聲，並且追蹤我的 <a href="https://medium.com/@chienchuanwang">Medium</a>！</li><li>歡迎在文章下方留言分享你的經驗或想法，我們一起進步！</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=19d6ea1a4801" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[SEO 讓你被看見：透過 Canonical URL 告訴 Google 你才是主人]]></title>
            <link>https://medium.com/@chienchuanwang/seo-%E8%AE%93%E4%BD%A0%E8%A2%AB%E7%9C%8B%E8%A6%8B-%E9%80%8F%E9%81%8E-canonical-url-%E5%91%8A%E8%A8%B4-google-%E4%BD%A0%E6%89%8D%E6%98%AF%E4%B8%BB%E4%BA%BA-740ffd8fa8f2?source=rss-8169ac429c8c------2</link>
            <guid isPermaLink="false">https://medium.com/p/740ffd8fa8f2</guid>
            <category><![CDATA[google]]></category>
            <category><![CDATA[html]]></category>
            <category><![CDATA[seo]]></category>
            <category><![CDATA[canonical]]></category>
            <category><![CDATA[web-development]]></category>
            <dc:creator><![CDATA[Chuan 建權]]></dc:creator>
            <pubDate>Tue, 09 Dec 2025 11:11:23 GMT</pubDate>
            <atom:updated>2025-12-09T11:11:23.740Z</atom:updated>
            <content:encoded><![CDATA[<h3>什麼是 Canonical URL？</h3><p>在 SEO 領域中，Canonical URL（標準網址） 是一個專門用來解決「重複內容問題」的工具。它是透過 HTML &lt;link&gt; 標籤中的 rel=&quot;canonical&quot; 屬性，告訴搜尋引擎：</p><p><strong>「這些內容有多個網址，但我要你把某一個 URL 當成正式版本。」</strong></p><p>搜尋引擎會因此把權重集中於你指定的網址，避免被當成重複內容而稀釋排名。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/704/1*tCJA8dycfbHp0CriKDFHgA.jpeg" /><figcaption>蜘蛛人迷因圖完全是為了這一刻而存在</figcaption></figure><h3>為什麼需要 Canonical URL？</h3><p>網站常常因為技術因素或使用者操作方式，導致「同一份內容可以被多個網址存取」。搜尋引擎看到這些不同網址時，可能誤以為是不同頁面，造成：</p><ul><li>排名權重被分散</li><li>搜尋引擎無法知道哪個頁面該排名</li><li>部分重複頁面甚至可能被視為低品質內容</li></ul><p>Canonical 的用途就是讓你清楚宣告：「其他頁面都只是副本，正式版本是這個 URL。」</p><h3>用比喻來理解</h3><p>想像你的文章是一份公司文件，但以下情況會產生多份影印本：</p><ul><li>加上追蹤參數的版本</li><li>排序方式不同的清單頁</li><li>複製到 tag 頁、archive 頁、AMP 頁</li><li>HTTP/HTTPS 各一份</li><li>有無斜線版本</li><li>同內容出現在不同 domain 或合作平台</li></ul><p>搜尋引擎像審查員，看見多份影印本，就會想：<strong>「到底哪一份是正式版？」</strong></p><p>此時 canonical 就像是在影印本的頁首貼上一張紙：<strong>「正式版在這裡，其餘都是副本。」</strong></p><p>搜尋引擎因此不會誤判，也不會把權重分散出去。</p><h3>Canonical URL 的使用方式</h3><p>Canonical 通常放在 &lt;head&gt;：</p><pre>&lt;link rel=&quot;canonical&quot; href=&quot;https://example.com/preferred-url&quot;&gt;</pre><p>搜尋引擎讀到這段標籤後會：</p><ul><li>了解你希望排名的 URL</li><li>把副本頁面的權重集中到 canonical 指定的頁面</li><li>避免重複頁面同時被索引</li><li>減少 SEO 風險與浪費爬蟲資源</li></ul><h3>實際實用情境</h3><ol><li>URL 出現追蹤參數（UTM、ref）</li></ol><ul><li>/product/123</li><li>/product/123?utm_source=fb</li><li>/product/123?ref=email</li></ul><p>實際內容完全相同 → canonical 指向主要 URL。</p><p>2. 分頁、排序、搜尋結果頁</p><ul><li>/products?sort=price_asc</li><li>/products?sort=latest</li><li>/products?page=2</li></ul><p>多數電商網站會 canonical 到 /products，避免相同內容分散。</p><p>但這邊要注意的是，Google 官方建議「分頁頁面應該 canonical 自己，而不是統一指向第 1 頁。」</p><p>所以 /products?page=2 應 canonical 到 &lt;link rel=&quot;canonical&quot; href=&quot;https://example.com/products?page=2&quot;&gt;。</p><p>3. http / https、www / non-www</p><p>網站轉換時常發生，但 canonical 能避免權重分裂。</p><ul><li><a href="http://example.com/page">http://example.com/page</a></li><li><a href="https://example.com/page">https://example.com/page</a></li></ul><p>都 canonical 到 https://example.com/page。</p><p>4. 內容被授權給第三平台（Medium、合作社群）</p><p>例如有人轉載你的文章，你要 canonical 回原文避免權重全部跑給對方，同時也記得在自己的文章頁面進行 canonical。</p><p>合作平台必須加上：&lt;link rel=&quot;canonical&quot; href=&quot;https://your-domain.com/original-article&quot;&gt;，不然外部平台可能會被 Google 判斷為原始來源。</p><p>如果無法在第三方平台進行 canonical，則盡量避免全文授權。</p><p>5. 同內容出現在 tag 頁、分類頁、歸檔頁</p><ul><li>/tags/seo/how-to-canonical</li><li>/category/search/how-to-canonical</li><li>/blog/how-to-canonical</li></ul><p>6. 正確 canonical 應指向文章主頁。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/609/1*XWc44rk3X9I4PLcjXOESYg.png" /><figcaption>每個都好像，但每個都不一樣，那你要跟 Google 說清楚啊！</figcaption></figure><h3>Canonical 的正確寫法</h3><ul><li>必須使用絕對 URL</li></ul><pre>&lt;link rel=&quot;canonical&quot; href=&quot;https://example.com/page&quot;&gt;</pre><ul><li>每頁只能有一個 canonical</li><li>canonical 必須能正確回應 200（不能 404 或 redirect）</li><li>canonical 指向自己（self-referencing），讓 Google 明確知道正式網址是哪個。</li></ul><blockquote><em>💡 Canonical vs 301 Redirect — — 何時使用哪個？</em></blockquote><blockquote><em>如果你需要保留副本但又想集中權重 → 用 canonical。</em></blockquote><blockquote><em>如果你不需要保留副本（舊網址完全要廢除） → 用 301 redirect。</em></blockquote><h3>最常見的 Canonical 錯誤</h3><ol><li>全部頁面都 canonical 到首頁（致命錯誤）， Google 會把整站當重複內容。</li><li>canonical 指向錯誤網址或不存在的頁面。</li><li>分頁頁面 canonical 都指向第 1 頁，正確做法通常是：</li></ol><ul><li>第 2 頁應 canonical 自己</li><li>並使用 rel=”next” / rel=”prev”（部分 SEO）</li></ul><p>4. 多語系 canonical 錯誤，導致語系互相覆蓋。</p><p>5. 同一頁誤放兩個 canonical。</p><p>Canonical 設定錯誤會造成 Google 不收錄你真正想呈現的頁面。</p><h3>Canonical URL 的總結</h3><p>Canonical URL 是網站 SEO 最重要的基礎設定之一，它能：</p><ul><li>告訴搜尋引擎哪個 URL 是正式版本</li><li>避免因重複內容造成排名權重分散</li><li>改善 Google 對網站內容的理解</li><li>提升搜尋引擎索引效率</li></ul><p><strong>正確設定 Canonical 是為了讓 Google 不混淆，並把所有 SEO 力量集中到你想要的那個網址上</strong>，所以有在經營自己網站的朋友們，從這一刻起開始 canonical 起來吧！</p><p>如果喜歡這篇文章：</p><ul><li>可以給我一個掌聲，並且追蹤我的 <a href="https://medium.com/@chienchuanwang">Medium</a>！</li><li>歡迎在文章下方留言分享你的經驗或想法，我們一起進步！</li></ul><h4>參考資料</h4><ul><li><a href="https://welly.tw/blog/what-is-canonical-url">Welly — Canonical URL是什麼？Canonical SEO的重要性報你知！</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=740ffd8fa8f2" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[可不可以幫個忙：PostgresSQL 的時區怎麼跟我想的不一樣]]></title>
            <link>https://medium.com/@chienchuanwang/%E5%8F%AF%E4%B8%8D%E5%8F%AF%E4%BB%A5%E5%B9%AB%E5%80%8B%E5%BF%99-postgressql-%E7%9A%84%E6%99%82%E5%8D%80%E6%80%8E%E9%BA%BC%E8%B7%9F%E6%88%91%E6%83%B3%E7%9A%84%E4%B8%8D%E4%B8%80%E6%A8%A3-5abb0514dfb2?source=rss-8169ac429c8c------2</link>
            <guid isPermaLink="false">https://medium.com/p/5abb0514dfb2</guid>
            <category><![CDATA[database]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[drizzle]]></category>
            <category><![CDATA[sql]]></category>
            <dc:creator><![CDATA[Chuan 建權]]></dc:creator>
            <pubDate>Sun, 28 Sep 2025 06:38:40 GMT</pubDate>
            <atom:updated>2025-10-02T02:20:33.918Z</atom:updated>
            <content:encoded><![CDATA[<h3>可不可以幫個忙：PostgreSQL 的時區怎麼跟我想的不一樣</h3><p>幾個月前帶專題課時，同學們問了一個問題：「助教，我的 PostgreSQL 有些欄位時間是台灣時區、有些不是，怎麼辦？」</p><p>當時我還不以為意，想說可能只是程式碼哪裡轉換時區忘了轉換，請同學檢查一下是不是哪邊沒有 Day.js 轉換，用 console.log 印出來確認一下，隔幾天也沒聽到同學反應後續，想說應該是解決了吧。</p><p>沒想到自己最近做 React.js 搭配 Drizzle ORM 的專案時，竟然遇到了一模一樣的地雷，還為此折騰了一番。</p><h4>情境概要</h4><p>我的 sessions table 裡有三個跟 timestamp 有關的欄位，分別是：</p><ul><li>created_at：使用者登入當下的時間。</li><li>expired_at：使用者該 session 過期的時間，預設為 created_at 往後加 14 天。</li><li>last_active_at：使用者 session 最後活躍的時間。（遇到特定事件觸發）</li></ul><p>Drizzle ORM 的程式碼大概是這樣，可以看最後三行：</p><pre>// session.js<br><br>export const sessions = pgTable(&quot;sessions&quot;, {<br>  id: varchar(&quot;id&quot;, { length: 100 }).primaryKey().notNull(),<br>  userId: integer(&quot;user_id&quot;).notNull().references(() =&gt; users.id),<br>  isRevoked: boolean(&quot;is_revoked&quot;).notNull().default(false),<br>  currentOrganizationId: integer(&quot;current_organization_id&quot;).references(() =&gt; organizations.id),<br>  ipAddress: varchar(&quot;ip_address&quot;, { length: 50 }),<br>  lastActiveAt: timestamp(&quot;last_active_at&quot;),  <br>  createdAt: timestamp(&quot;created_at&quot;).notNull().defaultNow(),<br>  expiresAt: timestamp(&quot;expires_at&quot;).notNull(),<br>});</pre><p>存入資料庫後得到的結果是：</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-F3XnoqxwsB9Htnqv99zWQ.png" /><figcaption>請看最右邊三欄</figcaption></figure><p>可以發現 created_at 的時間明明是 9/27 的 22:56，那 expires_at 預想應該要是 10/11 的 22:56，怎麼硬生生少了八個小時，而這八小時不難猜，肯定是「<strong>時區 timezone</strong>」在搞鬼，但是是誰在搞鬼？</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/481/1*GQKSc3AxXYgJWhZpUcCVjg.jpeg" /></figure><h4>問題出在哪？</h4><p>首先回去看 created_at 的寫法是使用 Drizzle ORM 的 defaultNow() 方法，而根據 Drizzle 的官方文件，defaultNow() 方法轉換為 SQL 時，會呼叫 DEFAULT now() 方法，官方還特別補了一句。</p><blockquote>which returns the current date and time with the time zone<br>會回傳當下日期與時間，附帶時區</blockquote><p>再來看看 expires_at 是怎麼寫的，重點在 const expiresAt 那行：</p><pre>export async function createSessionRecord(userId, currentOrganizationId, ipAddress) {<br>  const sessionId = nanoid()<br>  const expiresAt = new Date(Date.now() + 14 * 24 * 60 * 60 * 1000) // 14 days<br><br>  try {<br>    await db.insert(sessions).values({<br>      id: sessionId,<br>      userId: parseInt(userId),<br>      currentOrganizationId: parseInt(currentOrganizationId),<br>      ipAddress,<br>      lastActiveAt: new Date(),<br>      expiresAt,<br>    })<br><br>    return sessionId<br>  } catch (err) {<br>    console.error(&quot;Error creating session record: &quot;, err)<br>    return null<br>  }<br>}</pre><p>可以看見 expires_at 是用 JS 的 Date.now() 方法往後加 14 天，然後再轉換 Date 格式，所以我們要去查查這個 Date.now() 實際上做了什麼。</p><p>根據 MDN 文件，Date.now() 的方法定義入如下：</p><blockquote>The Date.now() static method returns the number of milliseconds elapsed since the epoch, which is defined as the midnight at the beginning of January 1, 1970, UTC.<br>Date.now() 靜態方法回傳自紀元（UTC 時間 1970 年 1 月 1 日午夜）以來經過的毫秒數。</blockquote><p>發現了嗎？原來 Date.now() 使用的是 UTC，難怪存入的時區不一樣。</p><h4>有哪些可能的解決辦法？</h4><p>這時候我們有幾個選擇：</p><ul><li>全部統一成台灣 +8 時區</li><li>全部統一成 UTC</li><li>搬去英國格林威治，肯定變成 UTC</li></ul><p>第三個方法成本太高，而第一個方法等於要回去把專案中所有的時間物件進行檢查，然後統一想辦法轉換成台灣時區，但這個的成本非常高，因為 JS 的 Date 物件根本沒有 timezone 相關的參數。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/500/1*uSiY52UJVPtEL3GJjvwS7g.jpeg" /><figcaption>加個 timezone 方法會死嗎</figcaption></figure><p>這時候可能會想說，那用 Day.js 轉總可以了吧？</p><p>先暴雷，行不通的！因為 Day.js 進行的轉換只是<strong>顯示上</strong>的轉換，實際上存入的秒數仍然是使用 UTC，這就像我們在台北買的電子機票，在美國看會顯示美國當地時間，但最後的源頭都還是 UTC。</p><p>所以最後我選擇「<strong>全部統一成 UTC</strong>」。</p><h4>如何統一？</h4><p>由於 JS 基本上都是使用 Date 物件，本來已是 UTC 的 Date 都不需要調整，代表只有 created_at() 這部分使用 Drizzle ORM 的部分需要調整。</p><p>這時候可以將本來 defaltNow() 改使用 default() 方法，明確指定存成 UTC 時區，如下：</p><pre>createdAt: timestamp(&quot;created_at&quot;).notNull().default(sql`NOW() AT TIME ZONE &#39;UTC&#39;`)</pre><p>還有另一個比較偷懶的方法，雖然我們人沒辦法搬去格林威治，但我們總可以把 PostgreSQL 資料庫設定成 UTC，而不要使用台灣時區吧！</p><p>我們先用 psql -U postgres 進到資料庫終端介面，然後進行下列操作：</p><pre>-- 顯示當前使用<br>SHOW timezone;<br><br>-- 更改指定 database 的時區<br>ALTER DATABASE &lt;database_name&gt; SET timezone TO &#39;UTC&#39;;<br><br>-- 進入指定 database<br>\c &lt;database_name&gt;<br><br>-- 再次確認是否修改成功<br>SHOW timezone;</pre><p>如果喜歡這篇文章：</p><ul><li>可以給我一個掌聲，並且追蹤我的 <a href="https://medium.com/@chienchuanwang">Medium</a>！</li><li>歡迎在文章下方留言分享你的經驗或想法，我們一起進步！</li></ul><h4>參考資料</h4><ul><li><a href="https://orm.drizzle.team/docs/guides/timestamp-default-value">Drizzle | SQL Timestamp as a default value</a></li><li><a href="https://stackoverflow.com/questions/15141762/how-to-initialize-a-javascript-date-to-a-particular-time-zone">How to initialize a JavaScript Date to a particular time zone</a></li><li><a href="https://neon.com/postgresql/postgresql-date-functions/postgresql-now">PostgreSQL NOW() Function</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=5abb0514dfb2" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[順便學 Ruby：如何在 Rails 裡面自訂驗證錯誤訊息？]]></title>
            <link>https://medium.com/@chienchuanwang/%E9%A0%86%E4%BE%BF%E5%AD%B8-ruby-%E5%A6%82%E4%BD%95%E5%9C%A8-rails-%E8%A3%A1%E9%9D%A2%E8%87%AA%E8%A8%82%E9%A9%97%E8%AD%89%E9%8C%AF%E8%AA%A4%E8%A8%8A%E6%81%AF-f98df069e534?source=rss-8169ac429c8c------2</link>
            <guid isPermaLink="false">https://medium.com/p/f98df069e534</guid>
            <category><![CDATA[ruby-on-rails]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[web-development]]></category>
            <category><![CDATA[rails]]></category>
            <category><![CDATA[programming]]></category>
            <dc:creator><![CDATA[Chuan 建權]]></dc:creator>
            <pubDate>Fri, 19 Sep 2025 06:12:47 GMT</pubDate>
            <atom:updated>2025-09-25T10:12:47.805Z</atom:updated>
            <content:encoded><![CDATA[<h3>順便學 Ruby：如何在 Rails 自訂驗證錯誤訊息？</h3><p>通常我們想在 Rails 針對某個欄位自訂驗證的錯誤訊息，會在 model 裡面使用 validates 驗證，並進行以下設定：</p><pre># coupon.rb<br><br>validates :name, presence: { message: &quot;折價券名稱不能為空&quot;},<br>                 length: { maximum: 10, message: &quot;折價券名稱最多只能 10 個字&quot;}</pre><p>如果沒有通過驗證時，此時看見返回的錯誤訊息會是「<strong>Name 折價券名稱最多只能 10 個字</strong>」。</p><p>在 Rails 的驗證錯誤訊息裡，預設會把 <strong>attribute 欄位名稱</strong>（這裡是 name）放在錯誤訊息前面，所以錯誤訊息的格式會是：</p><pre>   :name + message<br>-&gt;  Name + 折價券名稱不能為空</pre><p>如果希望拿掉預設的 attribute 名稱，讓 Rails 只返回自訂錯誤訊息，有兩種做法：</p><h3>方法一：使用 validate + errors</h3><p>簡單來說，就是自定義驗證方式，並且設定對應的錯誤訊息：</p><pre># coupon.rb<br><br>validate :custom_name_validation<br>def custom_name_validation<br>  if name.blank?<br>    errors.add(:base, &quot;折價券名稱不能為空&quot;)<br>  elsif name.length &gt; 10<br>    errors.add(:base, &quot;折價券名稱最多只能 10 個字&quot;)<br>  end<br>end</pre><p>這樣得到的錯誤訊息會是「<strong>折價券名稱最多只能 10 個字</strong>」，而沒有 Name 前綴。</p><p>如果需要更進一步針對錯誤訊息進行 i18n，可以將本來硬編碼的錯誤訊息，改成使用 I18n.t 方法來進行翻譯處理。</p><p>承接剛剛的程式碼進行修改：</p><pre># coupon.rb<br><br>validate :custom_name_validation<br>def custom_name_validation<br>  if name.blank?<br>    errors.add(:base, I18n.t(&quot;errors.messages.coupon_name_blank&quot;))<br>  elsif name.length &gt; 10<br>    errors.add(:base, I18n.t(&quot;errors.messages.coupon_name_too_long&quot;))<br>  end<br>end</pre><blockquote><em>這邊記得要到 i18n 檔案中進行 </em><em>errors.messages 的相關對應設定，不然會沒有翻譯，通常翻譯檔案會存放在 </em><em>config/locales/zh-TW.yml。</em></blockquote><h3>方法二：將 i18n 的 attribute 名稱設定為空字串</h3><p>Rails 會透過 i18n 的 activerecord.attributes 找到屬性的顯示名稱。</p><p>以剛剛的折價券名稱為例，如果在 i18n 檔案中進行設定（例如：config/locales/zh-TW.yml）：</p><pre># config/locales/zh-TW.yml<br><br>zh-TW:<br>  activerecord:<br>    attributes:<br>      coupon:<br>        name: &quot;&quot;</pre><p>這樣一樣可以使用驗證的錯誤訊息變成「<strong>折價券名稱最多只能 10 個字</strong>」。</p><p>然而，如果希望要讓錯誤訊息針對各國進行翻譯，那就要多進行一些修改。</p><h3>針對 i18n 的改良版本</h3><p>首先要將本來 model 的驗證部分改為「僅設定驗證條件」：</p><pre># 驗證條件仍為「必填、字串長度最大為 10」<br>validates :name, presence: true, length: { maximum: 10 }</pre><p>然後到 config/locales/zh-TW.yml 進行設定：</p><pre>tw:<br>  activerecord:<br>    attributes:<br>      coupon:<br>        name: &quot;&quot;<br>  errors:<br>    models:<br>      coupons:<br>        attributes:<br>          name:<br>            blank: &quot;折價券名稱不能為空&quot;<br>            too_long: &quot;折價券名稱最多只能 10 個字&quot;</pre><p>這邊的 blank、too_long 都是 Rails 內建 validator 對應的錯誤符號（error symbol），所以當我們在 model 裡使用 validates 時，Rails 會自動產生對應的錯誤 key，也就是 blank、too_long 等，然後去 i18n 檔案裡找尋翻譯。</p><p>Rails 將 validator 跟 i18n key 對應起來的流程大概是這樣：</p><ul><li>我們在 model 定義好驗證條件</li></ul><pre>validates :name, presence: true, length: { maximum: 10 }</pre><ul><li>如果使用者在 name 欄位填入空字串，Rails 會在 PresenceValidator 裡呼叫：</li></ul><pre>errors.add(:name, :blank)</pre><p>:blank 就是那個錯誤符號。</p><ul><li>errors.add 會去 i18n 裡找路徑，並且依序按照下方的路徑逐層查找，看先在哪邊找到：</li></ul><pre>activerecord.errors.models.coupon.attributes.name.blank<br>activerecord.errors.models.coupon.blank<br>activerecord.errors.messages.blank<br>errors.attributes.name.blank<br>errors.messages.blank</pre><ul><li>找到對應翻譯後，將該翻譯文字套入 errors.full_message。</li></ul><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/c98387937e21589f749aa1d0be73f0f7/href">https://medium.com/media/c98387937e21589f749aa1d0be73f0f7/href</a></iframe><h3>小結</h3><p>客製錯誤訊息有時候是件很細碎、很惱人的事，尤其是需要使用「非英文」字句顯示錯誤訊息，本來只要輕鬆一行能解決的事，變成要繞好多圈才能達成我們字字斟酌的結果，做來做去會想：「算了，就中英混雜吧！」，但為了自己最理想的前端畫面，只好深究 Rails 的 i18n 設定，這時候只能安慰自己：「至少 Rails 可以讓我們修改。」</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/498/1*ywxPU0icra34F9iP6DMs2A.png" /><figcaption>沒有需求，沒有煩惱</figcaption></figure><h3>延伸資源</h3><ul><li><a href="https://guides.rubyonrails.org/active_record_validations.html">Rails Guides — Active Record Validations</a></li><li><a href="https://guides.rubyonrails.org/i18n.html">Rails Guides — I18n API</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f98df069e534" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>