如何看懂陌生專案

您在 IDE 中開啟一個第一次看到的專案資料夾：裡面有幾十個巢狀資料夾、陌生的名稱，沒有任何檔案是您親手寫的。接下來您要修改專案：先做一些小幅的頁面調整，再新增遊戲。動手之前，先弄清楚需要的檔案在哪裡，以及專案有哪些規範。

很容易一個接一個打開資料夾，盼著碰巧找到目標。不如先掌握專案的大致結構和規範。無論是小幅修改，還是之後新增遊戲，都用得上這些資訊：您得替檔案命名、找好存放位置，再和 Claude Code 一起檢查結果。

先找到專案的入口

先查看 IDE 面板中的檔案樹，在專案根目錄找找 README.md。這是寫給人看的普通文字檔，不是程式讀取的檔案；通常會簡單說明專案的用途和啟動方式。不過，有時裡面只有專案名稱，外加一句"剩下的請自行摸索"。人嘛，難免偷懶，README 不會自己寫好 :)

README 通常能提供三項資訊：專案用途、啟動方式，以及更詳細的說明連結，例如架構或程式碼格式規範的獨立檔案。若只是小幅修改頁面，這些資訊已足以讓您掌握大致情況。

README 可能不存在，也可能已經跟不上程式碼。把它當作起點就好：指令和資料夾的資訊還是要對照專案檔案確認。如果說明描述的結構和檔案樹不一樣，先記下來，之後再查證。

從資料夾樹看出什麼

來看一個練習用的例子：小型瀏覽器遊戲入口網站，有遊戲展示頁、得分機制和排行榜。它的部分檔案樹如下：

project/
├── README.md
├── package.json
├── vite.config.js
├── pages/
│   └── leaderboard.html
├── src/
│   ├── leaderboard.js
│   └── reward-flow.js
├── assets/
├── tests/
└── dist/

即使還沒讀過任何一行程式碼，光看檔案樹也能發現一些線索：

資料夾名稱只能提供線索，不能當成定論。從檔名來看，src/leaderboard.js 似乎是目標；接著要讀讀看，確認它在哪裡載入。上表描述的也只是資料夾可能的用途，仍得查證。例如，光有 tests/ 資料夾，還看不出檢查要怎麼執行。

另外要分清楚原始碼，以及由原始碼產生或從外部安裝的內容。dist/ 通常由建置工具根據 src/ 的內容產生；第三方相依套件資料夾（常見名稱是 node_modules/，這個例子裡沒有）則根本不是您團隊成員寫的。幾乎不值得從這些地方開始讀：在那裡修改的內容不是下次建置時就消失，就是屬於您不會直接編輯的外部程式碼。套件管理工具、安裝相依套件和 lockfile 格式是另一個主題，這裡先不談。

還有一點：範例中的資料夾組合不是標準。在其他專案裡，頁面可能放在 public/，原始碼則放在 app/。尋找的思路一樣，只是名稱不同。

專案的工作規範

假設您已經了解各資料夾的用途。新增檔案前，先弄清楚專案慣用的工作方式。有些專案把所有頁面放在同一個資料夾；有些則讓每款遊戲和自己的腳本、圖片放在一起。兩種做法都可能合適。問題出在新增遊戲時突然採用第三種方式，卻找不到任何理由。

從 README 的連結尋找專案規範。如果有 CONTRIBUTING.md，通常會說明如何貢獻修改。文件中可能寫著檔案的存放規則，而 CLAUDE.md 則可能是給代理的指示。個別資料夾也可能有自己的 README，補充該資料夾內容的細節。別期待每個專案都備齊這些檔案；有時幾條重要規範就寫在根目錄的 README 裡。

第一次修改前，只要先確認哪些原始檔可以改、檔案怎麼命名和存放、專案怎麼啟動，以及如何檢查結果。如果指示說不能編輯建置產物，就去找原始檔；如果新增頁面時也要更新說明，現在就把這件事寫進任務裡。

如果沒有書面規範，就看看兩三個相似範例。要新增遊戲時，研究相鄰的遊戲通常比隨手打開一個文件資料夾更有用。相同的檔案配置方式可以作為參考，但一個舊檔案還不足以證明整個專案都遵循同一套做法。

有時情況更麻煩：README 說頁面放在 pages/，最近新增的遊戲卻在別處。這時可以直接問專案負責人："文件寫著頁面放在 pages/，但最近兩款新遊戲都在 games/。下一款應該放哪裡？"不要默默挑一個自己喜歡的做法，也別為了整齊就搬動整棵目錄樹。

檔案與資料夾的命名規範

命名是一套名稱約定。好的名稱讓您在檔案樹中找到目標，也能在開啟前看出用途。在我們的入口網站裡，leaderboard.html 一看就知道是排行榜；page2.html 卻只透露它大概是某個編號。

名稱包含意義和格式。意義回答"這裡放什麼？"，格式則決定字母大小寫和單字分隔方式。舉例來說，每日獎勵頁面可以有幾種命名方式：

這些只是不同的寫法，不代表排名。如果專案頁面的名稱使用連字號，新頁面也沿用相同風格即可。不過，不同類型的檔案可以採用不同規範：常見的 README.md 不必為了和 HTML 頁面一致而改成小寫。工具預期會找到的名稱也要保持原樣。

假設我們約定入口網站的一般檔案使用英文和 kebab-case。那麼 snake-preview.png 就比 img3.png 清楚：它是貪食蛇遊戲的預覽圖。game-icons/ 比 stuff/ 更能說明內容。leaderboard-final-new.html 下次修改後很快就名不符實；正式使用的頁面最好採用能長期表示用途的名稱。

同一種東西只用一個術語。如果專案裡的遊戲資料夾叫 games，卻又為同一類內容新增 plays，讀者就得猜兩者是否不同。除非專案規範已經有約定，否則別把單字縮成 ldrbrd/ 這類謎題。

拼寫也得精確。檔案名稱和路徑必須一致，包括大小寫：Snake.png 和 snake.png 不能視為同一個檔案。這種錯誤在某台電腦上可能沒被發現，換個環境就會出現。在我們的例子裡，統一使用小寫能減少這類差異。

資料夾的層級規範

名稱決定了，接下來要找存放位置。巢狀資料夾適合用來整理清楚的一組內容：遊戲頁面、某款遊戲的圖片、共用圖示。每增加一層，都應該讓內容更容易找到。

假設換一種做法：入口網站不斷擴大，所有檔案都直接放在根目錄：

project/
├── README.md
├── package.json
├── snake.html
├── tetris.html
├── leaderboard.html
├── snake.js
├── tetris.js
├── snake-preview.png
└── tetris-preview.png

小範例還算容易看懂。等遊戲增加到二十款，頁面、腳本和圖片就會互相干擾。我們的入口網站已經把內容分成 pages/、src/ 和 assets/，新增遊戲時沿用這種方式就很合理。以下是新增遊戲後可能的部分結構：

project/
├── pages/
│   ├── leaderboard.html
│   └── games/
│       ├── snake.html
│       └── tetris.html
├── src/
│   ├── leaderboard.js
│   └── games/
│       ├── snake.js
│       └── tetris.js
└── assets/
    └── games/
        ├── snake/
        │   └── preview.png
        └── tetris/
            └── preview.png

遊戲頁面集中在一個資料夾，腳本則放在另一個。遊戲名稱讓彼此相關的檔案一目了然。圖片會放進特定遊戲的資料夾，所以簡短的 preview.png 就夠了：完整路徑已經說明這是哪款遊戲的預覽圖。之後這款遊戲有其他圖片，也可以放在同一個資料夾。

另一個極端是這種路徑：pages/portal/content/browser/games/arcade/snake/screens/main/index.html。開啟單一頁面要經過許多層，有些名稱也沒提供多少資訊。如果專案並沒有不同入口網站、畫面和類別之分，這種結構只會增加工作，沒有實際好處。

資料夾深度沒有"最多三層"這種通用標準。逐層確認它的用途：這一層整理了哪些內容？有助於和旁邊的群組區分嗎？有時根據工具或專案規範，單一檔案也得放在獨立資料夾裡。不過，只因為"以後可能會放東西"就先建資料夾，通常還太早。

上面的檔案樹示範了這個例子的演進。如果您的專案已經把每款遊戲完整放在自己的資料夾裡，就繼續沿用。新增遊戲本身並不是重整其他遊戲的理由。

共用檔案和遊戲專屬檔案放哪裡

貪食蛇遊戲新增了蘋果圖片，整個入口網站則共用一個 Logo。兩者都是圖片，使用方式卻不同：蘋果只屬於一款遊戲，Logo 則會出現在展示頁、排行榜和遊戲頁面。

單一遊戲的檔案只供這款遊戲使用。本節把這類檔案稱為專屬檔案：指的是使用範圍，而不是存放在本機或伺服器上。在這個檔案樹中，蘋果圖片會放在 assets/games/snake/apple.png。共用檔案則供多個部分使用；如果專案採用這種資料夾，Logo 可以放在 assets/shared/portal-logo.svg。shared 代表"共用"，但資料夾名稱本身不會賦予檔案任何特殊性質。

樣式和腳本也適用同樣的區分。貪食蛇遊戲區域的樣式只屬於這款遊戲，網站共用頁首的樣式則供整個入口網站使用。決定存放位置時，先看看目前有哪些地方會用到這個檔案。別為了日後可能重複使用，就預先把所有東西都移到共用資料夾。

反過來說，把同一個 Logo 複製到每款遊戲的資料夾也不方便：要替換時，得把每份副本都找出來。如果它確實是共用資源，最好讓所有地方都指向同一個檔案。至於不同遊戲的兩張相似圖片，可以各自獨立保存：看起來相像，不代表將來一定要一起修改。

圖中有三支箭頭指向共用 Logo，只有一支指向蘋果圖片。因此，替換 Logo 後要查看三個頁面，替換蘋果圖片後則檢查貪食蛇。修改前，可以請 Claude Code 找出哪些檔案引用了該資源：實際的引用可能比資料夾名稱透露的更多。

移動和重新命名時要檢查什麼

重新命名檔案只要一秒，但舊名稱可能已經寫在連結和設定裡。移動檔案還會改變它和其他檔案的相對位置。因此，整理檔案樹和修改頁面內容一樣，都算是專案修改。

再看一個移動檔案的例子：把頁面 pages/snake.html 移到 pages/games/snake.html。腳本仍留在原處：src/games/snake.js。這個例子中的相對路徑是從 HTML 頁面的位置開始計算。移動後，載入腳本的路徑也得修改：

<!-- 移動前：pages/snake.html -->
<script src="../src/games/snake.js" type="module"></script>

<!-- 移動後：pages/games/snake.html -->
<script src="../../src/games/snake.js" type="module"></script>

每個 ../ 都會讓路徑往上一層。現在從 games/ 得先回到 pages/，再回到根目錄，最後才能進入 src/。腳本本身沒變，舊路徑卻已經失效。

還有反向引用：展示頁上的遊戲卡片可能仍然連到頁面的舊位置。移動之前，先在整個專案中搜尋舊路徑。移動後更新相關連結、載入路徑、建置設定和文件範例。腳本若有重新命名，也要檢查 import，也就是其他腳本載入它的陳述式。

IDE 可能會自動更新部分連結，但結果仍得檢查。路徑不一定都以完整字串寫出來，有時是資料夾名稱和檔名拼接而成。搜尋舊名稱能找出相依關係，再執行相關流程則有助於發現遺漏。

如何檢查修改結果

先從專案文件找出啟動、建置和檢查指令。如果是有 package.json 的專案，就把文件中的指示和 scripts 區段對照。指令名稱依專案而異；光有 tests/ 資料夾還看不出該執行什麼。如果沒有說明，就先確認檢查方式，不要隨便套用熟悉的指令。

接著要根據修改內容來檢查。移動貪食蛇頁面後，從展示頁的遊戲卡片開啟，這樣就能同時確認連結和遊戲是否載入。檢查圖片有沒有顯示，以及遊戲能不能啟動。修改共用 Logo 後，也要看看排行榜和另一個遊戲頁面。

建置成功很有幫助，但不能取代這些步驟：舊連結可能仍留在建置結果中。記下哪些項目已經檢查，哪些還沒。例如："建置成功，貪食蛇可從展示頁開啟並啟動；尚未檢查窄螢幕上的顯示效果。"

最後看看修改過的檔案清單。新增一款遊戲，預期會修改遊戲檔案和展示頁。如果其他遊戲的資料夾遭到重新命名，或大量圖片被覆寫，就應該查明原因。現在花點時間查看，比之後追查意外故障省事。

如何把規範交代給 Claude Code

只說"把遊戲加得整齊一點"，會把太多決定留給代理。不如描述清楚任務，先請它了解專案慣例。新遊戲的路徑應該符合專案結構，而不是跟著代理一時的偏好走。

穩定且經過確認的規範可以寫進 CLAUDE.md。以我們的練習用入口網站為例，內容可能像這樣：

## 檔案與資料夾
- 一般檔案和資料夾使用英文與 kebab-case 命名。
  保留 README.md 和 CLAUDE.md 這些既定名稱。
- 遊戲頁面放在 pages/games/，遊戲腳本放在 src/games/。
- 單一遊戲的資源放在 assets/games/<game-name>/。
- 入口網站共用的圖片放在 assets/shared/。
- 移動或重新命名檔案時，一併更新指向該檔案的引用
  和檔案內的相對路徑。

## 檢查
- 從 README.md 查找啟動和檢查指令。
- 從展示頁開啟新遊戲，並確認遊戲能啟動。
- 修改共用資源後，檢查所有使用它的頁面。

這是已確認的規範範例，不是通用的檔案樹範本。要在自己的專案加入類似內容前，先對照實際檔案確認路徑和指令。如果代理只是猜測資料夾用途，請它提出依據；別把猜測寫成永久規範。

現在，新增遊戲的任務可以這樣描述：

請根據附上的說明，在入口網站新增 memory-match 遊戲。
請閱讀 README.md、CLAUDE.md，以及任務涉及資料夾中的指示。
看看兩款現有遊戲的檔案是怎麼安排的。
請提出新頁面、腳本和圖片的名稱與路徑。
指出需要修改哪個展示頁檔案，以及如何檢查結果。
如果指示和專案現況不一致，請先提問。
先提出計畫並等候確認，再開始修改。

有了計畫，您就能先檢視具體安排：遊戲會放在哪裡、哪些檔案會共用，以及修改是否會影響其他頁面。完成修改後，請代理列出改過的檔案和執行過的檢查。這樣您就能更容易核對結果是否符合原先確認的內容。