Cách làm quen với một dự án lạ

Bạn mở một thư mục dự án trong IDE lần đầu tiên: hàng chục thư mục lồng nhau, tên gọi lạ lẫm, chẳng có tệp nào do chính bạn viết. Bạn sắp sửa thay đổi dự án: trước tiên là chỉnh sửa nhỏ trên các trang, sau đó thêm trò chơi mới. Trước khi bắt đầu, hãy tìm hiểu các tệp cần thiết nằm ở đâu và dự án có những quy ước nào.

Rất dễ mở lần lượt từng thư mục với hy vọng tình cờ tìm đúng chỗ. Tốt hơn hết là nắm được cấu trúc tổng thể và các quy ước của dự án trước. Chúng hữu ích cho cả một chỉnh sửa nhỏ lẫn lúc bạn muốn thêm trò chơi mới: bạn cần chọn tên tệp, tìm vị trí đặt chúng rồi kiểm tra kết quả cùng Claude Code.

Bắt đầu từ điểm vào dự án

Hãy xem cây tệp trong khung IDE và tìm README.md ở thư mục gốc dự án. Đây là tệp văn bản thông thường do người viết cho người đọc, chứ không phải cho chương trình: README thường giải thích ngắn gọn dự án này là gì và cách chạy nó. Nhưng đôi khi bên trong chỉ có tên dự án cùng niềm hy vọng rằng bạn sẽ tự tìm ra mọi thứ. Con người vốn lười, mà README thì không tự viết được :)

Meme: bình luận được viết rất kỹ, còn README.md thì soạn qua loa.

Thông thường, README cho bạn biết ba điều: mục đích của dự án, cách chạy và các liên kết đến hướng dẫn chi tiết hơn, chẳng hạn một tệp riêng về kiến trúc hoặc quy ước định dạng mã. Với một chỉnh sửa nhỏ trên trang, chừng đó thường đủ để bạn hình dung tổng thể.

README có thể không tồn tại hoặc không còn khớp với mã hiện tại. Hãy xem nó như điểm khởi đầu: đối chiếu thông tin về lệnh và thư mục với các tệp trong dự án. Nếu README mô tả một cấu trúc nhưng cây tệp lại cho thấy cấu trúc khác, hãy ghi lại để kiểm tra.

Đây là lúc Claude Code có thể giúp bạn: yêu cầu agent đọc README và liệt kê những đường dẫn hữu ích cho việc đang làm - chưa chỉnh sửa gì cả, chỉ tìm kiếm thôi. Agent đọc tệp nhanh hơn bạn và có thể gợi ý ngay nơi cần tìm bảng xếp hạng.

Cây thư mục cho biết điều gì

Hãy xem một ví dụ minh họa: cổng trò chơi trên trình duyệt, có trang danh sách trò chơi, hệ thống tính điểm và bảng xếp hạng. Một phần cây thư mục trông như sau:

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

Ngay cả khi chưa đọc dòng mã nào, cây thư mục cũng đã gợi ý được vài điều:

Thư mục hoặc tệp	Vai trò có thể có
`README.md`	mô tả dự án và cách chạy
`package.json`	danh sách dependency và lệnh của dự án
`vite.config.js`	cấu hình chạy và build bằng Vite
`pages/`	các trang được trình duyệt mở
`src/`	mã nguồn: các script được trang sử dụng
`assets/`	hình ảnh, biểu tượng và các tệp tĩnh tương tự
`tests/`	các bước kiểm tra mã tự động
`dist/`	kết quả build, được tạo tự động

Tên thư mục chỉ là gợi ý, không phải xác nhận. Tệp src/leaderboard.js có vẻ phù hợp dựa trên tên gọi; giờ hãy đọc nó và tìm xem nó được kết nối vào trang ở đâu. Bảng trên mô tả vai trò dự kiến của các thư mục, nhưng vẫn cần kiểm chứng. Chẳng hạn, có thư mục tests/ cũng chưa cho biết phải chạy kiểm tra bằng cách nào.

Cũng cần phân biệt mã nguồn với những thứ được tạo ra từ mã đó hoặc được cài từ bên ngoài. dist/ thường được công cụ build tạo từ nội dung trong src/, còn thư mục dependency bên thứ ba (thường có tên node_modules/, dù ví dụ này không có) vốn không do nhóm của bạn viết. Hầu như chẳng có ích gì khi bắt đầu đọc chúng: thay đổi ở đó có thể mất sau lần build tiếp theo hoặc thuộc về mã bên ngoài mà bạn không trực tiếp chỉnh sửa. Package manager, cài dependency và định dạng lockfile là chủ đề khác, không bàn ở đây.

Thêm một điều nữa: cấu trúc thư mục trong ví dụ không phải tiêu chuẩn chung. Ở dự án khác, các trang có thể nằm trong public/, còn mã nguồn nằm trong app/. Cách tìm vẫn vậy, chỉ khác tên thư mục.

Quy ước làm việc với dự án

Giả sử bạn đã hiểu vai trò của các thư mục. Trước khi thêm tệp, hãy tìm hiểu cách mọi người làm việc trong dự án này. Có dự án để tất cả trang trong một thư mục chung, có dự án lại lưu từng trò chơi cùng script và hình ảnh riêng. Cả hai cách đều có thể hợp lý. Rắc rối bắt đầu khi trò chơi mới được sắp xếp theo một nguyên tắc thứ ba mà chẳng có lời giải thích nào.

Tìm các quy ước qua liên kết trong README. Nếu có tệp CONTRIBUTING.md, tệp này thường giải thích cách đóng góp thay đổi. Tài liệu có thể nêu quy tắc đặt tệp, còn CLAUDE.md chứa hướng dẫn cho agent. Một thư mục riêng cũng có thể có README với thông tin cụ thể về nội dung bên trong. Đừng mặc định dự án nào cũng có đủ mọi thứ này: đôi khi vài quy tắc cần thiết nằm gọn trong README ở thư mục gốc.

Với lần chỉnh sửa đầu tiên, chỉ cần biết những tệp nguồn nào được phép sửa, cách đặt tên và vị trí của chúng, cách chạy dự án và kiểm tra kết quả. Nếu hướng dẫn không cho sửa sản phẩm build, hãy tìm tệp nguồn. Nếu hướng dẫn yêu cầu cập nhật mô tả khi thêm trang, hãy đưa việc đó vào yêu cầu ngay từ đầu.

Nếu không có quy tắc bằng văn bản, hãy xem hai hoặc ba ví dụ tương tự. Khi thêm trò chơi mới, xem các trò chơi gần giống sẽ hữu ích hơn mở ngẫu nhiên một thư mục tài liệu. Bạn có thể lấy cách sắp xếp giống nhau làm mẫu, nhưng một tệp cũ chưa đủ để kết luận toàn dự án đều theo cách đó.

Đôi khi tình hình còn rắc rối hơn: README chỉ đến pages/, nhưng các trò chơi mới nhất lại nằm ở chỗ khác. Khi đó, hãy hỏi cụ thể người phụ trách dự án: "Hướng dẫn nói dùng pages/, nhưng hai trò chơi mới lại nằm trong games/. Nên thêm trò tiếp theo vào đâu?" Đừng âm thầm chọn cách mình thích hoặc chuyển cả cây thư mục chỉ để mọi thứ trông đồng nhất.

Quy ước đặt tên tệp và thư mục

Quy ước đặt tên là sự thống nhất về cách đặt tên. Tên tốt giúp bạn tìm đúng tệp trong cây thư mục và đoán được mục đích trước khi mở. Trong cổng trò chơi của chúng ta, leaderboard.html gợi ý đây là bảng xếp hạng, còn page2.html chỉ cho biết một số thứ tự nào đó.

Tên tệp có cả ý nghĩa lẫn hình thức. Ý nghĩa trả lời câu hỏi "tệp này chứa gì?", còn hình thức quy định kiểu chữ và dấu phân cách giữa các từ. Chẳng hạn, trang phần thưởng hằng ngày có thể được đặt tên theo vài cách:

Kiểu	Ví dụ tên tệp	Cách nối các từ
kebab-case	`daily-rewards.html`	chữ thường, các từ cách nhau bằng dấu gạch nối
snake_case	`daily_rewards.html`	chữ thường, các từ cách nhau bằng dấu gạch dưới
camelCase	`dailyRewards.html`	từ đầu viết thường, các từ sau viết hoa chữ cái đầu
PascalCase	`DailyRewards.html`	mọi từ đều viết hoa chữ cái đầu

Đây là các cách viết, không phải thứ hạng. Nếu tên các trang trong dự án dùng dấu gạch nối, hãy đặt tên trang mới theo cùng kiểu. Tuy vậy, các nhóm tệp khác nhau có thể theo những quy ước riêng: không cần đổi tên quen thuộc README.md thành chữ thường chỉ để giống các trang HTML. Tên mà công cụ mong đợi cũng cần được giữ nguyên.

Giả sử nhóm thống nhất dùng từ tiếng Anh và kiểu kebab-case cho các tệp thông thường trong cổng trò chơi. Khi đó snake-preview.png dễ hiểu hơn img3.png: đây là ảnh xem trước của trò Snake. Thư mục game-icons/ nói rõ nội dung hơn stuff/. Tên leaderboard-final-new.html sẽ nhanh chóng lỗi thời sau lần chỉnh sửa tiếp theo; với trang dùng lâu dài, nên giữ tên ổn định theo chức năng.

Hãy dùng một thuật ngữ nhất quán cho cùng một loại đối tượng. Nếu trò chơi trong dự án được gọi là games, tạo thêm thư mục plays cho cùng nhóm sẽ khiến người đọc phải tự hỏi chúng có khác nhau không. Đừng rút gọn từ thành những cái tên khó đoán như ldrbrd/ nếu dự án không có quy ước dùng cách viết tắt đó.

Viết chính xác cũng quan trọng. Tên tệp và đường dẫn phải khớp, kể cả chữ hoa chữ thường: đừng xem Snake.png và snake.png là hai tên có thể thay thế cho nhau. Lỗi có thể không lộ ra trên máy này nhưng lại xuất hiện trong một môi trường khác. Trong ví dụ của chúng ta, quy ước viết chữ thường giúp giảm những sai khác như vậy.

Cấu trúc thư mục lồng nhau

Đã chọn được tên. Câu hỏi tiếp theo là đặt tệp ở đâu. Thư mục con hữu ích khi nó gom một nhóm rõ ràng: trang trò chơi, ảnh của một trò chơi, biểu tượng dùng chung. Mỗi cấp thư mục mới nên giúp bạn tìm nội dung dễ hơn.

Thử hình dung một cách khác: cổng trò chơi phát triển, nhưng mọi tệp đều được đặt ngay ở thư mục gốc:

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

Với ví dụ nhỏ này, bạn vẫn có thể tìm ra mọi thứ. Nhưng khi số trò chơi lên đến hai mươi, trang, script và hình ảnh sẽ lẫn vào nhau. Cổng trò chơi của chúng ta đã chia thành pages/, src/ và assets/, vậy nên khi thêm trò chơi, hợp lý nhất là tiếp tục cách đó. Dưới đây là một phần cấu trúc có thể có sau khi thêm như vậy:

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

Cây thư mục dự án trong IDE: trang nằm trong pages, script trong src, ảnh Snake và Tetris trong assets/games.

Các trang trò chơi được gom vào một nhóm, còn script của chúng nằm trong nhóm khác. Tên trò chơi giúp liên kết các tệp với nhau. Hình ảnh được đặt trong thư mục riêng của từng trò, vì vậy tên ngắn preview.png là đủ: đường dẫn đầy đủ đã cho biết ảnh xem trước thuộc trò nào. Thư mục riêng cũng tiện để lưu các hình ảnh khác của trò chơi đó.

Thái cực ngược lại là đường dẫn kiểu pages/portal/content/browser/games/arcade/snake/screens/main/index.html. Để mở một trang, bạn phải đi qua rất nhiều cấp, mà một số tên hầu như không bổ sung thông tin gì. Nếu dự án không có các cổng, màn hình và danh mục riêng, cấu trúc như vậy chỉ tạo thêm việc vô ích.

Không có giới hạn chung kiểu "không quá ba thư mục". Hãy xem ý nghĩa của từng cấp: nó gom những gì, có giúp phân biệt nhóm này với nhóm bên cạnh không? Đôi khi một thư mục chỉ có một tệp vẫn cần thiết theo quy ước của công cụ hoặc dự án. Nhưng thường chưa cần tạo thư mục chỉ vì "biết đâu sau này sẽ có thứ gì đó ở đây".

Cây thư mục trên minh họa cách ví dụ của chúng ta phát triển. Nếu mỗi trò chơi trong dự án của bạn đã được lưu trọn vẹn trong thư mục riêng, hãy tiếp tục cách đó. Chỉ riêng việc thêm trò chơi mới không phải lý do để sắp xếp lại những trò còn lại.

Nơi lưu tệp dùng chung và tệp riêng

Trong trò Snake có thêm hình quả táo, còn cả cổng trò chơi dùng chung một logo. Cả hai đều là hình ảnh nhưng được sử dụng theo cách khác nhau. Quả táo chỉ dành cho một trò chơi, còn logo xuất hiện trên trang danh sách trò chơi, bảng xếp hạng và các trang trò chơi.

Tệp riêng của một trò chơi chỉ được dùng trong trò đó. Ở đây, ta gọi những tệp như vậy là tệp riêng: nói về phạm vi sử dụng, không phải nơi lưu trên máy tính hay server. Trong cây thư mục của chúng ta, quả táo sẽ nằm ở assets/games/snake/apple.png. Tệp dùng chung phục vụ nhiều phần; nếu dự án có quy ước này, ta có thể tạo assets/shared/portal-logo.svg để lưu logo. Từ shared có nghĩa là "dùng chung", nhưng bản thân tên thư mục không tạo ra thuộc tính đặc biệt nào cho tệp.

Sự phân biệt tương tự cũng hữu ích với stylesheet và script. Phần trình bày bàn chơi Snake thuộc về trò đó, còn phần đầu trang chung thuộc về toàn bộ cổng trò chơi. Khi chọn vị trí, hãy hỏi xem hiện tại những phần nào đang dùng tệp này. Đừng chuyển mọi thứ vào thư mục dùng chung từ trước chỉ để phòng trường hợp sau này cần dùng lại.

Ngược lại, sao chép cùng một logo vào thư mục của từng trò cũng bất tiện: khi thay logo, bạn phải tìm mọi bản sao. Nếu đó thực sự là một tài nguyên chung, hãy tham chiếu đến cùng một tệp. Hai hình ảnh tương tự của các trò khác nhau vẫn có thể độc lập: trông giống nhau không có nghĩa là chúng sẽ luôn được thay đổi cùng lúc.

Mũi tên đi từ các trang đến tài nguyên mà chúng sử dụng.

Trong sơ đồ, có ba mũi tên trỏ đến logo dùng chung, nhưng chỉ một mũi tên trỏ đến hình quả táo. Vì vậy, sau khi thay logo, hãy kiểm tra cả ba trang; sau khi thay ảnh quả táo, hãy kiểm tra Snake. Trước khi chỉnh sửa, bạn có thể yêu cầu Claude Code tìm những tệp tham chiếu đến tài nguyên đó: các liên kết thực tế có thể nhiều hơn những gì tên thư mục gợi ý.

Cần kiểm tra gì khi di chuyển hoặc đổi tên

Đổi tên tệp chỉ mất một giây, nhưng tên cũ có thể đã được ghi trong các liên kết và cấu hình. Di chuyển tệp còn làm thay đổi vị trí của nó so với các tệp khác. Vì vậy, sắp xếp lại cây thư mục cũng là một thay đổi của dự án, giống như chỉnh sửa nội dung trang.

Hãy xem một ví dụ riêng về việc di chuyển: trang pages/snake.html được chuyển đến pages/games/snake.html. Script vẫn ở nguyên chỗ cũ, tại src/games/snake.js. Trong ví dụ này, đường dẫn tương đối được tính từ vị trí của trang HTML. Sau khi di chuyển, cần sửa đường dẫn kết nối:

<!-- Trước khi di chuyển: pages/snake.html -->
<script src="../src/games/snake.js" type="module"></script>

<!-- Sau khi di chuyển: pages/games/snake.html -->
<script src="../../src/games/snake.js" type="module"></script>

Mỗi đoạn ../ đưa đường dẫn lên cao hơn một thư mục. Giờ từ games/ cần quay lại pages/, rồi lên thư mục gốc, sau đó mới vào src/. Bản thân script không đổi, nhưng đường dẫn cũ đến nó không còn đúng.

Cũng có những liên kết theo chiều ngược lại: thẻ trò chơi trên trang danh sách vẫn có thể trỏ đến địa chỉ trang cũ. Trước khi di chuyển, hãy tìm mọi chỗ trong dự án nhắc đến đường dẫn cũ. Sau đó cập nhật các liên kết, chỗ kết nối, cấu hình build và ví dụ trong tài liệu. Nếu đổi tên script, hãy kiểm tra cả các import - những dòng mà script khác dùng để kết nối với nó.

IDE có thể tự cập nhật một số liên kết, nhưng bạn vẫn cần xem lại kết quả. Không phải đường dẫn nào cũng được ghi nguyên thành một chuỗi: đôi khi địa chỉ được ghép từ tên thư mục và tên tệp. Vì vậy, tìm tên cũ sẽ giúp phát hiện các phụ thuộc, còn chạy thử đúng kịch bản sử dụng sẽ giúp nhận ra chỗ bị bỏ sót.

Cách kiểm tra thay đổi

Trước tiên, hãy tìm trong tài liệu dự án các lệnh chạy, build và kiểm tra. Nếu dự án có package.json, hãy đối chiếu hướng dẫn với mục scripts trong tệp này. Tên lệnh tùy thuộc vào dự án; chỉ riêng việc có thư mục tests/ không cho biết cần chạy gì. Nếu thiếu hướng dẫn, hãy hỏi cách kiểm tra thay vì đoán một lệnh quen thuộc.

Tiếp theo, cách kiểm tra tùy vào thay đổi bạn đã thực hiện. Sau khi di chuyển trang Snake, hãy mở trang này từ thẻ trò chơi trên trang danh sách: như vậy bạn sẽ kiểm tra cả liên kết lẫn việc tải trò chơi. Xác nhận hình ảnh đã xuất hiện và trò chơi chạy được. Nếu sửa logo dùng chung, hãy xem cả bảng xếp hạng và một trang trò chơi khác.

Build thành công là điều tốt, nhưng không thay thế các bước này: liên kết đến địa chỉ cũ vẫn có thể còn trong sản phẩm build. Hãy ghi lại những gì bạn đã kiểm tra và phần nào chưa kiểm tra. Ví dụ: "Build thành công, Snake mở được từ trang danh sách trò chơi và chạy bình thường; chưa kiểm tra hiển thị trên màn hình hẹp".

Cuối cùng, xem lại danh sách tệp đã thay đổi. Khi thêm một trò chơi, ta thường mong đợi các tệp của trò đó và thay đổi trên trang danh sách trò chơi. Nếu thấy thư mục của trò khác bị đổi tên hoặc nhiều hình ảnh bị ghi đè, cần có lời giải thích. Bước xem lại này nhanh hơn nhiều so với việc tìm lỗi bất ngờ sau đó.

Cách cung cấp quy ước cho Claude Code

Yêu cầu "thêm trò chơi cho gọn gàng" để agent tự quyết định quá nhiều thứ. Tốt hơn là mô tả nhiệm vụ và yêu cầu agent tìm hiểu các quy ước trước. Đường dẫn của trò chơi mới nên theo cấu trúc dự án, không phải sở thích ngẫu nhiên của agent.

Bạn có thể ghi các quy tắc ổn định, đã được xác nhận vào CLAUDE.md. Với cổng trò chơi minh họa của chúng ta, nội dung có thể như sau:

## Tệp và thư mục
- Đặt tên các tệp và thư mục thông thường bằng từ tiếng Anh theo kiểu kebab-case.
  Giữ nguyên các tên đã được quy ước như README.md và CLAUDE.md.
- Các trang trò chơi nằm trong pages/games/, script trò chơi nằm trong src/games/.
- Tài nguyên riêng của từng trò chơi nằm trong assets/games/<game-name>/.
- Hình ảnh dùng chung của cổng trò chơi nằm trong assets/shared/.
- Khi di chuyển hoặc đổi tên tệp, cập nhật các liên kết đến tệp đó
  và đường dẫn tương đối bên trong tệp.

## Kiểm tra
- Lấy lệnh chạy và kiểm tra từ README.md.
- Mở trò chơi mới từ trang danh sách trò chơi và kiểm tra xem nó có chạy không.
- Sau khi thay đổi tài nguyên dùng chung, kiểm tra các trang sử dụng nó.

Đây là ví dụ về các quy ước đã được thống nhất, không phải mẫu cây thư mục dùng cho mọi dự án. Trước khi ghi nội dung tương tự vào dự án của bạn, hãy đối chiếu đường dẫn và lệnh với các tệp thực tế. Nếu agent chỉ đoán vai trò của một thư mục, hãy yêu cầu nó nêu căn cứ; đừng biến phỏng đoán thành hướng dẫn lâu dài.

Giờ đây, yêu cầu thêm trò chơi có thể viết như sau:

Hãy thêm trò chơi memory-match vào cổng theo mô tả đính kèm.
Đọc README.md, CLAUDE.md và hướng dẫn trong các thư mục liên quan đến nhiệm vụ.
Xem cách sắp xếp tệp của hai trò chơi hiện có.
Đề xuất tên và đường dẫn cho trang mới, script và hình ảnh.
Cho biết cần sửa tệp nào của trang danh sách trò chơi và kiểm tra kết quả ra sao.
Nếu hướng dẫn không khớp với cấu trúc dự án, hãy hỏi lại.
Trước tiên hãy trình bày kế hoạch, chờ tôi duyệt rồi mới sửa.

Trong kế hoạch, bạn đã có thể đánh giá các quyết định cụ thể: trò chơi sẽ nằm ở đâu, tệp nào sẽ dùng chung, thay đổi có ảnh hưởng đến trang bên cạnh không. Sau khi chỉnh sửa, hãy yêu cầu agent liệt kê các tệp đã thay đổi và bước kiểm tra đã thực hiện. Như vậy bạn sẽ dễ đối chiếu kết quả với những gì đã duyệt.