Communitygithub.com

作品集起步

從「我想要一個作品集或個人網站」問到上線:選最簡單的技術棧,用占位內容搭好頁面,做上線前檢查,再部署到對方自己的 GitHub 和 Vercel。

作品集起步 是什麼?

帶人從零做出自己能改的個人站。先問用途和已有經驗,再定技術棧、頁面、占位內容、正式內容和網域,上線前有一次檢查。程式和託管都在對方自己的帳號裡。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/helenvholmes/portfolio-starter/tree/main/skills/start

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Portfolio 入門套件

最終,對方應該擁有一個完全屬於自己的網站(程式碼存放在他們的 GitHub 中,主機則在他們的 Vercel 帳戶下),並且他們要足夠了解這個網站以便日後更新,而且在任何人看到之前,該網站已通過上線前的稽核。

如果你是在 GitHub 上閱讀此文件

通常,對方會先請你閱讀此儲存庫,而不是直接安裝。在執行步驟 0 之前,請先取得一份你可以執行腳本的副本,放在他們的專案資料夾之外,這樣此儲存庫的任何內容都不會混入他們的網站中:

git clone --depth 1 https://github.com/helenvholmes/portfolio-starter "${TMPDIR:-/tmp}/portfolio-starter"

然後,從該副本中閱讀 skills/start/SKILL.md 和 skills/accounts-setup/SKILL.md,並從那裡執行腳本(skills/accounts-setup/scripts/check.sh)。如果 git 尚未安裝,則改為從網路上閱讀這些檔案,並從 accounts-setup 的步驟 2 開始,該步驟會安裝 git;等 git 就緒後再進行複製。當對方在後續的會話中回來並表示要繼續時,請以同樣的方式再次閱讀這些技能,然後查看專案(其 README、開啟的 Pull Request 以及 Vercel 專案)來找出你上次中斷的地方。

如何進行工作

這裡的每個步驟都遵循三條規則:

  • 對方有意識地做出的決定就是他們的決定。 他們的品味、他們的用詞、他們對顏色或版面的選擇:提出建議,但絕不覆蓋。不過,當某個選擇對某人來說無法使用時(例如對比度太低、文字太小),要明確指出,並提供能保留其意圖的最小修正。
  • 用真實的內容進行測試。 對方會自己撰寫內容,因此請用他們實際會放在網站上的內容來檢查,而不是虛構的最壞情況。
  • 每次變更都應小而可逆。 在提交前先展示變更,每次變更獨立進行,並且不要留下任何測試用的輔助程式碼。

與對方交談

  • 每則訊息都要保持簡短。 通常幾句話就夠了;太長的訊息他們只會瀏覽或跳過。以他們需要做或決定的事情開頭,然後就停止。不要重述你剛才做了什麼,不要有開場白,也不要長篇大論地重複他們的回答。只有在需要他們遵循的步驟或需要他們選擇的選項時,才使用列表。一次只問一個問題。如果還有更多要說的,可以提出來(例如「想了解細節嗎?」)而不是直接寫出來。
  • 第一次提到新術語時,用一句簡單明瞭的話來解釋(../accounts-setup/references/glossary.md 中有用詞可參考)。配合他們的說話方式;如果他們很熟悉,就跳過解釋。
  • 他們希望你進行建置。在推薦技術棧和頁面(步驟 2)後進行確認,並在步驟 5 中使用「接下來做什麼?」這個問題讓他們在之後引導方向。除此之外,繼續進行,無需詢問。
  • 不要敘述過程或安撫他們:不要說「這是計畫」,不要說「在你確認之前什麼都不會建置」,也不要用「太好了!」開頭。只要完成工作、展示結果,然後問一個需要回答的問題。
  • 在執行任何難以復原的操作之前,要先告知對方:例如將儲存庫設為公開、連接網域名稱、或刪除任何東西。
  • 絕不要在聊天中要求密碼或令牌。帳戶設定有自己的技能來處理這個。

0. 帳戶

首先,確認這次會話是在對方自己的電腦上執行,還是在遠端或雲端機器上執行(../accounts-setup/SKILL.md 的步驟 0 說明了如何判斷,以及哪些步驟取決於你的工具)。在雲端環境中,下面標示為 Cloud 的步驟會取代本機步驟:不需要安裝任何東西,所有工作都存放在他們在開始前建立的 GitHub 儲存庫中,並且他們可以透過 Vercel 預覽連結來查看草稿。

執行 ../accounts-setup/scripts/check.sh。如果缺少 git、GitHub CLI 或 Node,或者他們尚未登入 GitHub,請先執行 accounts-setup 技能再回來。強烈建議使用 Vercel 連接器(它可以讓你在發生錯誤時讀取建置日誌),但非必要:步驟 3 也可以透過 Vercel 網站來完成。

Cloud: 跳過 check.sh,因為它檢查的是對方自己的電腦。改為按照 accounts-setup 中的「在雲端中」操作:確認你可以推送到他們的儲存庫,並且 Vercel 工具已就緒。

1. 訪談

一次只問一個問題,如果他們之前的答案已經涵蓋了某個問題,就跳過。如果你的工具可以顯示選擇題卡片(在 Claude 中,請參閱 ../accounts-setup/references/claude.md),請在以下每個問題中使用它:選項可以使回答更快速,而且對方總是可以改為自行輸入答案。將每個問題保持在一行,每個選項保持在幾個字。對於沒有卡片選項的問題,就以純文字提問。不要對每個答案發表評論;直接進入下一個問題。

  1. 這個網站主要是用來做什麼的? 求職 · 接案

  2. 你有可以分享的履歷嗎? 有,我會附上 · 這裡是我的 LinkedIn 個人檔案 · 目前沒有

    履歷可以幫助你更快地描述他們:用它來草擬介紹頁和關於頁面,並建議哪些角色和專案可以成為案例研究。你根據履歷草擬的一切都只是他們編輯的起點,要用他們的語氣;絕對不要添加履歷中沒有的主張、頭銜或數字。除非他們要求,否則不要在網站上保留個人詳細資訊(電話號碼、家庭住址)。LinkedIn 個人檔案通常需要登入才能閱讀,所以如果他們發送連結,請他們將個人檔案儲存為 PDF 格式(在他們的個人檔案頁面上,更多或資源按鈕 → 儲存為 PDF;LinkedIn 的功能位置可能會變動)並將該 PDF 附上。如果他們兩者都沒有,就繼續進行;在撰寫關於頁面時,請他們提供幾句關於他們工作的描述。

  3. 網站上會放什麼內容?(可複選)案例研究 · 文章 · 照片 · 履歷

  4. 需要任何附加功能嗎?(可複選)只要頁面 · 動畫 · 聯絡表單 · 更多功能

  5. 你有想要的外觀嗎? 我有 Figma 檔案 · 我有喜歡的網站或圖片 · 還沒有,給我個驚喜

    如果他們有 Figma 檔案、網站或圖片,請以純文字請他們提供連結或圖片:連結和圖片都可以,越多越好。如果你有 Figma 工具,可以使用它們來讀取 Figma 連結;如果沒有,或者該連結是私有的,請他們將畫板匯出為圖片並附上。仔細查看他們分享的所有內容,並用一句話回饋你從中得到的資訊(類型、顏色、版面感覺),以便他們可以糾正你。

  6. 是否有任何頁面需要設為私密,需要密碼才能存取? 沒有 · 有,一份簡報或提案 · 有,NDA 工作或推薦信

  7. 你有網域名稱嗎,例如 yourname.com? 沒有,還沒有 · 有

    如果有的話,接著問:你是在哪裡購買的? GoDaddy · Namecheap · Squarespace · Cloudflare。如果他們不確定,可以請他們在電子郵件中搜尋該網域名稱加上「收據」或「續約」。請以純文字詢問網域名稱本身,以及它目前是否指向一個現有的網站,因為連接它將會取代該網站。

  8. 還有其他我們沒有提到的需求嗎? 沒有,我們開始建置吧 · 有(由他們輸入)

假設他們日後會透過 AI 助手來更新網站,因此內容會以檔案形式存放在儲存庫中。

直接進入步驟 2;其訊息開頭會用一兩行總結你聽到的內容,因此不需要另外進行確認。

2. 推薦技術棧和計畫(一次確認)

參考 references/stacks.md 進行選擇,然後發送一封簡短的訊息,讓他們可以在 1 分鐘內閱讀完。開頭用一兩行總結你聽到的內容,然後列出:

  • 你將用來建置的工具,每個工具用幾個字說明為什麼適合他們(例如「主要是可閱讀的專案,因此使用純頁面,不需要 JavaScript 來增加出錯風險」)
  • 頁面(/、/work、/work/<project>、/about、……)
  • 費用(通常免費)以及他們需要維護的內容
  • 一個替代方案,用一行說明,僅在決策非常接近時才提供

預設採用最簡單且可行的方案:靜態頁面、內容以檔案形式存放在儲存庫中、無資料庫、無客戶端 JavaScript,除非某個需求明確需要它。在命名之前,先查詢最新的穩定版本;不要依賴記憶。

最後以一個問題結尾,如果可以的話使用卡片:聽起來可以嗎? 是,開始建置 · 修改一些東西。一旦他們同意,就立刻開始建置。如果他們要修改,調整後繼續進行;不要再問一次。

除非他們問起,否則細節由你決定:內容模型、資料夾結構和設計權杖是你的決定。將外觀放在一個設計權杖檔案中(顏色、字型、字型大小、間距),這樣未來重新設計樣式時就不需要在各個元件中尋找。如果他們沒有提供設計方向,根據他們告訴你的內容選擇一個品味良好的中性方案,並用一句話說明;他們會對預覽做出反應,這比在抽象中選擇要容易得多。

3. 建立儲存庫並連接 Vercel

在建置之前完成這個步驟,意味著你推送的每次變更都會在一兩分鐘內反映在他們網站的網址上,這樣他們從一開始就可以在手機上查看。

Cloud: 儲存庫已經存在,因此跳過建立步驟(下面的步驟 1 和 4)。按照下面的方式推送到 main;如果會話不允許推送到 main,則推送一個分支:開啟一個 Pull Request,並引導他們每次在 GitHub 上點擊合併,用一句話說明,不要解釋分支。將初始檔案放入目前的檢出目錄中,保留他們的 README 直到新的 README 取代它,然後提交並在連接 Vercel 之前推送到 main。

  1. 詢問儲存庫名稱(建議像 portfolio 或他們的網域名稱去掉點號),並確認是公開還是私有。
  2. 使用該框架的官方入門套件(最小模板)來初始化專案。新增一個 .gitignore 檔案,涵蓋 node_modules、建置輸出、.env* 和作業系統檔案,以及一個 .nvmrc 檔案,指定 Node 的主要版本。
  3. 將入門套件的首頁替換為一行佔位文字(「網站即將上線」),以免半成品被發佈出去。
  4. 提交,然後建立並推送儲存庫:gh repo create <name> --public|--private --source=. --push。邊做邊解釋提交和推送。
  5. 將其連接到 Vercel,以便推送能自動部署。在 Vercel 網站上逐步引導他們操作,點擊每個按鈕(或者,如果 Vercel 工具可以建立和連結專案,可以提出幫他們完成):新增 → 專案 → 匯入儲存庫(第一次時,Vercel 會要求安裝其 GitHub 應用程式;選擇僅限此儲存庫即可)→ 確認框架預設已被偵測到 → 部署。如果他們屬於多個 Vercel 團隊,請確認該專案是放在他們選擇的團隊下。如果儲存庫不在 Vercel 的清單中,表示他們的 GitHub 應用程式對 Vercel 的存取權限僅限於其他儲存庫:請他們按照該頁面上的連結調整存取權限並加入此儲存庫,而不是授予它所有儲存庫的存取權限。告訴他們 Vercel 提供的 *.vercel.app 網址就是他們的網站:它是公開的,但在他們分享之前沒有人知道,因此非常適合用於草稿。
  6. 如果 Vercel 連接器已設定好,則透過它確認專案及其首次部署。如果建置失敗,請透過它讀取日誌並進行修復。

總是在 main 分支上工作。 不要建立分支或 Pull Request:對於初學者來說,這些是多餘的概念,而且這個網站也不需要它們。每次推送到 main 都會更新他們網站的網址。絕對不要推送必須保持私密的內容(例如密碼保護頁面的真實內容、個人詳細資訊),直到保護機制已就位並經過檢查。

4. 建置

使用明顯是假的佔位內容來建置計畫(例如「專案標題」、「Lorem ipsum」風格的摘要、灰色佔位圖片),這樣沒有人會誤以為是真實內容。包括:

  • 從 320px 寬度開始的回應式版面,基於相同設計權杖的淺色和深色主題,尊重 prefers-reduced-motion(動畫效果更溫和,不一定是完全沒有動畫)
  • 語意化的 HTML,可見的焦點樣式,內容模型中要求必填的替代文字欄位
  • 404 頁面、頁面標題和描述、社交分享圖片、網站地圖、robots.txt
  • 案例研究僅以卡片形式顯示一次。 作品頁面(以及首頁上任何精選作品)將每個案例研究以卡片形式列出一次:包含封面圖片、標題、一行摘要和年份。不要同時新增相同專案的表格或文字列表;將每項工作顯示兩次會讓人感覺是填充內容。
  • 聯絡方式:電子郵件優先。 這個網站的目的是幫助他們求職或接案,因此最簡單的聯絡方式就是電子郵件連結,在顯示聯絡資訊的地方(頁尾、關於頁面、案例研究結尾)應優先且最顯著地顯示它。LinkedIn 排在其次。只有在他們要求時才新增其他個人檔案(GitHub、Dribbble、Instagram 等)。在他們提供真實資訊之前,使用明顯是假的佔位內容,當你詢問電子郵件時,建議一個他們樂意公開的郵件地址,因為頁面上的任何內容都可以被任何人看到。
  • 在 vercel.json(或框架的等效檔案)中設定安全性標頭:CSP、frame-ancestors、X-Content-Type-Options、Referrer-Policy
  • 一份用白話文寫成的 README:如何執行、如何新增專案或文章、發佈流程是如何運作的

立即展示成果。 一旦第一個版本建置完成,就在背景啟動開發伺服器,並在對方可以看到的瀏覽器中開啟其網址:如果你的工具有內建瀏覽器或預覽窗格(在 Claude 中,請參閱 ../accounts-setup/references/claude.md),否則就使用他們的預設瀏覽器。在工作的時候讓它保持執行,這樣每次變更都會在你進行時立即顯示,並用一句話告訴他們網址。Cloud: 沒有他們可以開啟的伺服器;跳過此步驟,並在步驟 5 中使用他們網站的網址。

以說明原因的小步驟進行提交,並在有值得一看的內容時推送到 main。第一次時用一句話解釋提交和推送。

5. 接下來做什麼(重複直到完成)

用一句話提供他們網站的 *.vercel.app 網址,這樣他們也可以在手機上查看(它無需登入即可開啟,這點與 Vercel 的預覽連結不同,因此不要發送預覽連結)。不要回顧你建置了什麼或列出還剩下什麼。然後,以問題卡片的形式詢問:

接下來你想做什麼?

  • 加入真實內容
  • 設定我的自訂網域(僅當他們有網域時才顯示此選項)
  • 設定密碼保護(僅當他們要求私密頁面時才顯示此選項)
  • 執行上線前檢查(僅在真實內容加入後才顯示此選項)

他們總是可以輸入其他內容,例如對外觀進行修改;執行修改、推送,然後再次詢問。在每項任務完成後,再次詢問同一個問題,並列出剩餘的選項,直到所有工作都完成;然後進入步驟 6。

加入真實內容

協助對…

…

[翻譯截斷]

相關技能