BR3AK 網站的公開建造記錄(09/05)

BR3AK 現在沒有商品可以賣。供應商還沒選定，材質還沒驗證。

一般的做法是等——等產品做出來，再一次把網站和商店開起來。這個站選擇相反：先用內容把品牌跑起來，商店留到真的有第一個產品再說。

整個站我花了 5 個小時蓋完。這篇記錄架構怎麼決定、實際用了什麼、以及你要自己蓋一個的話怎麼開始。

一條硬要求，篩掉大部分選項

整個架構是從一句話推出來的：

我可以用 Claude Code 運營這個品牌，不用登入後台。

這不是修辭。它是一條會篩掉很多技術選項的硬要求——下面每一個決定都是從它來的。

為什麼不用 Shopify 官方的 Hydrogen

Shopify 有自己的前端框架 Hydrogen，跑在自家的託管平台 Oxygen 上。直覺是「要跟 Shopify 深度整合，就該用官方那套」。

查下去有兩個發現。

第一，Agent 能力跟前端框架無關。 每一個 Shopify 商店本身就自動有 MCP 端點，不需要 API key，也不需要另外建 app：

• https://{shop}.myshopify.com/api/mcp — 政策、FAQ、訂單
• https://{shop}.myshopify.com/api/ucp/mcp — 商品目錄查詢

Hydrogen 提供的那個端點只是把它 proxy 到自有網域，不是 MCP 的來源。所以「要 Agent 原生就得用 Hydrogen」這個推論不成立——Next.js 一樣拿得到。

第二，Hydrogen 跟「先免費上線」互斥。 Hydrogen 必須綁一個 Shopify 商店，Oxygen 必須是付費方案。走那條路等於在一件產品都還沒有之前，就得先開始付費。

所以前端是 Next.js on Vercel，商店開關現在是關的。

目前實際用的技術棧

層	用什麼
框架	Next.js 16（App Router）+ React 19
部署	Vercel，push 到 main 自動部署
內容	repo 裡的 MDX 檔，gray-matter 解 frontmatter、next-mdx-remote 渲染
資料庫	沒有
內容驗證	zod schema，frontmatter 寫壞會在 build 時就失敗
語系	[locale] 動態路由，英文預設 + 繁中，各自獨立網址
設定	單一 brand.config.ts——品牌名、網域、語系、選單、描述全在這裡
文案	一個雙語檔，中英成對，長文才進 MDX

SEO 基建（這層要一開始就做，事後補很痛）：sitemap.xml、robots.txt、每頁 canonical 與 hreflang、RSS feed，以及四種 JSON-LD 結構化資料——Organization、Brand、BlogPosting、BreadcrumbList。

給機器讀的端點：

• /api/brand.json — 品牌名、標語、描述、語系、選單，全部機器可讀
• /api/products.json — 商品清單（現在是空的）
• /llms.txt — 給語言模型的站台說明

人用網頁，Agent 用 JSON。這一層現在就先鋪好。

零資料庫

站上所有內容——品牌故事、文章、頁面文案——都是 repo 裡的檔案。這不是省事，是架構要求。

檔案：直接編輯 → commit → push → 自動部署。全程在終端機裡。 資料庫：要憑證、要走 API、要有發布腳本、要處理 migration。每多一個資料庫，就多一道非得登入後台不可的門——正好違反那條硬要求。

將來接上商店時，界線也是同一條：有即時狀態的東西（商品、庫存）留在商店那邊，不在自己這裡存第二份。 存第二份一定會過期，而過期的資料是電商最糟的 bug。

反過來，品牌故事、文章、頁面文案這些留在 repo——這正是要讓 Agent 直接改的東西。

代價是沒有 /admin 介面。如果將來團隊有非工程成員要自己改內容，正確解法不是回去開資料庫，而是 git-based 的編輯器（Keystatic、TinaCMS、Decap）——給人一個編輯畫面，背後寫的還是 git 裡同一份檔案。

這個站是在終端機裡蓋的

實際流程就是上面那句話的展開：Claude Code 改檔案 → 跑一次 build → commit → push，Vercel 接手。

換一張首頁的圖、改一個品牌術語、新增一個頁面、發一篇文章——全部是同一個動作。沒有登入任何後台，沒有點過任何管理介面。這篇文章本身也是這樣寫出來的。

那 5 個小時實際踩到的坑

架構本身不花時間，決定完就是照著做。真正吃掉時數的是這些。

沒有商品，卻留著一堆電商元件。 站上原本有尺寸選擇器、配色色票、加入購物車按鈕。沒有商品時這些全是雜訊，但更麻煩的是把「加入購物車」改成內容 CTA 之後——按鈕上寫著 READ THE JOURNAL，連結卻指向另一個頁面。文字與目的地不符這種錯，看畫面看不出來，要去讀 href 才會發現。

text-transform: uppercase 會吃掉品牌詞的大小寫。 品牌的設計概念本來寫成 ReForm，靠中間那個大寫 F 讓人讀成 re + form（重新成形），而不是 reform（改革、矯正）。但站上有三處是 uppercase，在那裡它被渲染成 REFORM，語意直接滑掉。最後改成 RE-FORM——連字號在大寫環境下不會消失。如果你的品牌詞靠大小寫承載語意，先確認 CSS 會不會把它吃掉。

改路由要一起 grep 內文連結。 把 /transparency 換成 /contact 時，about 頁和文章內文有四處 markdown 連結指向舊路由，全部會變 404。路由改名不是改一個檔案的事。

grep 預設大小寫敏感。 全站換術語時漏掉了一個全大寫的 TRANSFORMABLE，因為搜的是小寫。當下回報「已清乾淨」，其實不完整。換術語要用 grep -i 再掃一次。

外部資源會悄悄變成依賴。 有一段 CSS 背景圖指向第三方 CDN 上的檔案。它能跑，所以不會有人注意——直到對方哪天刪檔或改內容，你的首頁就跟著壞掉或被換掉。已經改成站內檔案。

去背圖要看它會落在哪個版位。 圖輯有兩格套了 mix-blend-mode: multiply，白底在那裡會被乘掉、看不出來；但同一張圖放到沒有 multiply 的版位，就會露出一塊白色方塊。素材本身沒問題，是版位決定它能不能用。

練習用 Claude Code 建站

如果你也想用這套架構，用 Claude Code 從零開始的順序大概是這樣。重點不是叫它「幫我做一個網站」，是先把界線定好，再讓它填。

1. 從乾淨的專案起步

create-next-app（TypeScript）。不要 fork 一個功能很多的既有專案再刪——刪不乾淨，而且你會一直在解別人的架構。

2. 先寫 AGENTS.md，再寫程式

這是整件事最關鍵的一步，也是最多人跳過的。在 repo 根目錄放一份 AGENTS.md，寫清楚這個專案的規則：內容放哪裡、文案怎麼分中英、什麼東西不准進 repo、改完要跑什麼指令。

Claude Code 每次進來都會讀它。沒有這份檔案，你每次都要重講一遍；有了它，規則變成專案的一部分。

3. 內容層：檔案 + schema 驗證

建 content/ 目錄放 MDX，用 gray-matter 解 frontmatter，然後用 zod 定義 schema，驗證失敗就讓 build 直接掛掉。

這一步是給 Agent 用的安全網。Agent 寫錯 frontmatter 是常態，有 schema 的話錯誤會在 build 時就爆出來，而不是悄悄上線變成壞頁面。

4. 單一設定檔

品牌名、網域、語系、選單、描述——全部集中在一個 brand.config.ts。選單改一處，topbar、footer、llms.txt、brand.json 全部跟著改。

這條的價值在你第一次改選單時就會兌現：如果選單散在四個地方，你一定會漏掉一個。

5. SEO 那層一次做完

sitemap.ts、robots.ts、canonical、hreflang、JSON-LD、feed。這些每一個品牌都會用到，而且事後補很痛——特別是雙語如果一開始沒有各自的網址，等於中文版對 Google 不存在，之後要救得動路由結構。

6. 商店開關先關著

在設定檔放一個 commerce.provider，值是 'none'。沒有產品之前不要碰 Shopify，先把內容站跑起來。

7. 真的要接商店時

守住同一條界線：不要把商品資料同步進 repo。 需要即時狀態的欄位就即時去問，前端只存一個對應用的識別字串。

8. 工作循環

改檔案 → npm run build → commit → push。讓 build 當守門員，跑過才推。

---

供應鏈還沒到位，這件事沒有被藏起來——它就寫在站上。內容先跑，產品跟上。