Terminal, thư mục dự án và trình quản lý gói

Bản đồ công trìnhTờ này lắp: Repo & CI, Coding agent

Bài nàyĐã họcChưa tớiĐã thay thế

Bạn sẽ học được gì

Tiêu chí nghiệm thu

Mở terminal và dùng 10 lệnh cơ bản trên macOS/Linux và Windows PowerShell.
Phân biệt đường dẫn tuyệt đối và tương đối, hiểu ký hiệu ~, ., ...
Nhận ra lệnh nguy hiểm khi agent xin quyền chạy.
Đọc hiểu package.json, node_modules, lockfile và khái niệm phụ thuộc.
Chạy các script dev, build, test, lint và hiểu từng cái làm gì.
Đọc một cây thư mục dự án Next.js và biết file nào quan trọng.

Terminal là gì và vì sao bạn cần nó

Phần lớn chúng ta dùng máy tính qua giao diện đồ họa (GUI): bấm biểu tượng, kéo thả, chọn menu. Giống gọi món bằng cách chỉ vào hình trên menu.

Terminal (còn gọi là dòng lệnh, command line) là cách nói chuyện với máy tính bằng chữ: bạn gõ một câu lệnh, máy thực hiện và trả lời bằng chữ. Giống đứng ở cửa bếp nói thẳng với bếp trưởng: “Lấy ba khay bột từ kho số 2 sang bàn số 1.” Nhanh, chính xác, nhưng phải nói đúng cú pháp.

Một vài từ hay đi cùng nhau:

Terminal: cửa sổ để gõ lệnh (Terminal trên macOS, Windows Terminal trên Windows, terminal tích hợp trong VS Code).
Shell: chương trình hiểu và thực hiện lệnh bên trong cửa sổ đó. macOS mặc định dùng zsh, Linux thường dùng bash, Windows dùng PowerShell.
Dấu nhắc (prompt): dòng chữ chờ bạn gõ, thường kết thúc bằng $, % (macOS/Linux) hoặc > (PowerShell, ví dụ PS C:\Users\Lan>).

Vì sao người không lập trình cần học terminal?

Ba lý do thực tế:

Coding agent sống trong terminal. Nhiều agent dòng lệnh chạy hẳn trong terminal; ngay cả agent tích hợp trong editor cũng chạy lệnh terminal để cài thư viện, chạy test, khởi động ứng dụng.
Bạn là người duyệt lệnh. Agent thường hỏi “Cho phép chạy lệnh npm install zod?” hoặc “Cho phép chạy rm -rf node_modules?” Bạn cần biết lệnh nào vô hại, lệnh nào có thể xóa mất dữ liệu.
Lỗi xuất hiện ở đây. Khi ứng dụng không chạy, thông báo lỗi nằm trong terminal. Đọc được nó là bước đầu để gỡ lỗi.

Cấu trúc một câu lệnh

Hầu hết câu lệnh có dạng:

Phiên agent

lệnh   tùy-chọn   đối-tượng
cp     -r         src/features/orders   src/features/orders-backup

Lệnh (cp): làm gì, ở đây là sao chép (copy).
Tùy chọn (flag, -r): làm theo cách nào, ở đây là sao chép cả thư mục và mọi thứ bên trong (recursive).
Đối tượng (argument): làm với cái gì; ở đây là nguồn và đích.

Bấm Enter để chạy. Terminal không có nút “Hoàn tác” như Word, nên đọc lại trước khi Enter là thói quen tốt.

10 lệnh terminal cơ bản

Bảng dưới đây là 10 lệnh đủ dùng cho 90% tình huống bạn gặp. Tin tốt: PowerShell trên Windows có sẵn bí danh (alias) cho nhiều lệnh kiểu macOS/Linux, nên ls, cd, cat, cp, mv, rm đều gõ được. Khác biệt chủ yếu nằm ở các tùy chọn.

#	Việc cần làm	macOS / Linux	Windows PowerShell	Ghi chú
1	Xem mình đang ở thư mục nào	`pwd`	`pwd` (tên đầy đủ: `Get-Location`)	“Print working directory”
2	Liệt kê file trong thư mục	`ls` (thêm file ẩn: `ls -la`)	`ls` hoặc `dir` (thêm file ẩn: `Get-ChildItem -Force`)	File bắt đầu bằng dấu chấm như `.env` là file ẩn
3	Đi vào một thư mục	`cd banhmoc-oms`	`cd banhmoc-oms`	`cd ..` để lùi ra thư mục cha
4	Tạo thư mục mới	`mkdir docs`	`mkdir docs`
5	Tạo file rỗng	`touch ghi-chu.md`	`New-Item ghi-chu.md`	PowerShell không có `touch`
6	Xem nội dung file	`cat package.json`	`cat package.json` (tên đầy đủ: `Get-Content`)	Chỉ xem, không sửa
7	Sao chép	`cp a.txt b.txt`; thư mục: `cp -r a b`	`cp a.txt b.txt`; thư mục: `Copy-Item a b -Recurse`
8	Di chuyển hoặc đổi tên	`mv cu.md moi.md`	`mv cu.md moi.md` (tên đầy đủ: `Move-Item`)	Đích đã tồn tại có thể bị ghi đè
9	Xóa	`rm file.txt`; thư mục: `rm -rf thu-muc`	`rm file.txt`; thư mục: `Remove-Item thu-muc -Recurse -Force`	Không qua thùng rác
10	Xóa màn hình	`clear`	`clear` hoặc `cls`	Chỉ làm sạch màn hình, không xóa gì khác

Ba thao tác bàn phím đáng giá hơn mọi lệnh:

Phím Tab: gõ vài chữ đầu của tên file/thư mục rồi bấm Tab, terminal tự điền phần còn lại. Đỡ gõ sai.
Mũi tên lên: gọi lại lệnh vừa chạy.
Ctrl + C: dừng lệnh đang chạy (ví dụ dừng ứng dụng đang chạy thử). Trong terminal, khi bạn không bôi đen chữ nào, Ctrl + C nghĩa là “dừng”, không phải “sao chép”.

Lệnh nào an toàn, lệnh nào cần cân nhắc khi agent xin quyền

Mức độ	Ví dụ	Thái độ
Chỉ đọc, vô hại	`ls`, `pwd`, `cat`, `git status`, `git diff`, `npm test`, `npm run lint`	Có thể cho phép thường xuyên
Thay đổi trong dự án, có đường lui	`npm install <gói>`, tạo/sửa file, `git commit`	Đọc tên gói, đọc thay đổi trước khi đồng ý
Nguy hiểm, khó hoặc không thể lùi	`rm -rf`, `git push --force`, `git reset --hard`, lệnh xóa dữ liệu database, lệnh có `sudo`	Dừng lại, hỏi agent lý do, chỉ chạy khi hiểu rõ

Bài Bảo mật khi dùng agent09-07 sẽ hướng dẫn cấu hình danh sách lệnh được phép và chế độ sandbox.

Bàn thử

Dán lệnh agent xin chạy → xếp ‘chỉ đọc / có đường lui / nguy hiểm’ theo bảng của bài, cảnh báo đường dẫn bắt đầu bằng / hoặc ~, –force, reset –hard, sudo, cat .env.local; có sẵn 8 lệnh của bài tập 3

Bàn thử cần bật JavaScript.

Kết quả chỉ để tham khảo, không thay cho việc bạn tự duyệt.

Đường dẫn tuyệt đối và tương đối

Mọi file trên máy nằm trong một cây thư mục. Đường dẫn (path) là cách chỉ đường tới một file trong cây đó.

Đường dẫn tuyệt đối (absolute path) đi từ gốc của ổ đĩa, giống địa chỉ đầy đủ: “Số 12, đường Phan Xích Long, phường…, TP.HCM”. Ở đâu đọc cũng tìm được.

Phiên agent

macOS / Linux:  /Users/lan/projects/banhmoc-oms/src/features/orders/tinh-tien.ts
Windows:        C:\Users\Lan\projects\banhmoc-oms\src\features\orders\tinh-tien.ts

Đường dẫn tương đối (relative path) tính từ chỗ bạn đang đứng, giống chỉ đường “qua hai nhà, rẽ trái”. Đúng hay sai phụ thuộc vào vị trí hiện tại.

Phiên agent

Đang đứng ở:    /Users/lan/projects/banhmoc-oms
Đường dẫn:      src/features/orders/tinh-tien.ts   (cùng file như trên)

Ba ký hiệu đặc biệt:

Ký hiệu	Nghĩa	Ví dụ
`~`	Thư mục cá nhân của bạn	`~/projects` = `/Users/lan/projects`
`.`	Thư mục hiện tại	`code .` mở thư mục hiện tại trong VS Code
`..`	Thư mục cha (lùi ra một cấp)	`cd ..`; liên kết `../01-nen-tang-may-tinh-va-web/...` trong chính chuỗi bài này

Hai khác biệt cần nhớ giữa hệ điều hành: macOS/Linux dùng dấu /, Windows dùng dấu \ (PowerShell chấp nhận cả /). Và macOS/Linux phân biệt chữ hoa chữ thường trong tên file (Order.ts khác order.ts), Windows thì mặc định không. Dự án chạy trên máy Windows nhưng hỏng trên server Linux đôi khi chỉ vì một chữ hoa.

Đọc lỗi terminal thường gặp

Thông báo	Nghĩa	Thường do
`zsh: command not found: npm` hoặc `bash: npm: command not found`	Shell không tìm thấy chương trình tên `npm`	Chưa cài Node.js, hoặc cài rồi nhưng chưa mở lại terminal
`The term 'npm' is not recognized as the name of a cmdlet, function, script file, or operable program.`	Tương tự, trên PowerShell	Như trên
`No such file or directory` / `Cannot find path ... because it does not exist.`	Đường dẫn không tồn tại	Gõ sai tên, hoặc đang đứng sai thư mục (kiểm tra bằng `pwd`)
`Permission denied`	Không có quyền	Đụng tới thư mục hệ thống, hoặc file đang bị chương trình khác dùng
`... cannot be loaded because running scripts is disabled on this system.`	PowerShell chặn chạy script	Chính sách bảo mật mặc định trên Windows; xem hướng dẫn ở bài 06-01
`Error: listen EADDRINUSE: address already in use :::3000`	Cổng 3000 đã có chương trình khác dùng	Ứng dụng đang chạy ở một terminal khác; dừng nó bằng Ctrl + C (riêng `npm run dev` của Next.js thường tự chuyển sang cổng khác như 3001 và báo cho bạn)

Câu đầu tiên khi gặp lỗi đường dẫn luôn là: “Mình đang đứng ở đâu?” Gõ pwd.

Hình chữ ký Phát lại phiên agent

zsh: command not found: npm
pwd
cd ~/projects/banhmoc-oms
npm run dev
npm install excel-export-helper-vn

Cấu trúc một dự án: đọc cây thư mục

Khi mở dự án banhmoc-oms, bạn sẽ thấy một cây thư mục tương tự thế này (rút gọn):

Phiên agent

banhmoc-oms/
├── AGENTS.md             # hướng dẫn cho coding agent
├── README.md             # giới thiệu dự án, cách chạy
├── package.json          # "danh sách nguyên liệu" và các lệnh của dự án
├── package-lock.json     # "biên nhận lô hàng": phiên bản chính xác của mọi thư viện
├── node_modules/         # "kho nguyên liệu": thư viện đã tải về (KHÔNG đưa vào Git)
├── next.config.ts        # cấu hình Next.js
├── tsconfig.json         # cấu hình TypeScript
├── .gitignore            # danh sách file Git bỏ qua
├── .env.example          # mẫu biến môi trường (không chứa bí mật)
├── .env.local            # biến môi trường thật trên máy bạn (KHÔNG đưa vào Git)
├── public/               # ảnh, logo, file tĩnh
├── docs/                 # PRD, spec, quyết định kiến trúc
├── src/
│   ├── app/              # các trang và route (Next.js App Router)
│   ├── components/       # khối giao diện dùng chung
│   ├── features/         # code theo tính năng: orders/, customers/, products/
│   ├── lib/              # tiện ích, kết nối database, đăng nhập
│   └── db/               # cấu trúc bảng, migration, dữ liệu mẫu
└── tests/
    ├── unit/             # kiểm thử từng hàm
    └── e2e/              # kiểm thử toàn luồng như người dùng thật

Không cần nhớ hết. Hãy nhớ ba nhóm:

Mã nguồn bạn sở hữu: src/, tests/, docs/, AGENTS.md. Đây là thứ cần review khi agent thay đổi.
Cấu hình: package.json, tsconfig.json, next.config.ts, .gitignore. Ít thay đổi, nhưng thay đổi ở đây ảnh hưởng toàn dự án, cần đọc kỹ.
Thứ được sinh ra tự động hoặc cục bộ: node_modules/, thư mục .next/ (kết quả build), .env.local. Không chỉnh tay, không đưa vào Git.

package.json: danh sách nguyên liệu và sổ lệnh

Mỗi dự án JavaScript/TypeScript có một file package.json ở thư mục gốc. Đây là “hồ sơ” của dự án. Một phiên bản rút gọn:

JSON

{
  "name": "banhmoc-oms",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint .",
    "typecheck": "tsc --noEmit",
    "test": "vitest run",
    "test:e2e": "playwright test"
  },
  "dependencies": {
    "next": "^16.0.0",
    "react": "^19.2.0",
    "react-dom": "^19.2.0",
    "zod": "^4.1.0",
    "drizzle-orm": "^0.44.0",
    "@supabase/supabase-js": "^2.58.0"
  },
  "devDependencies": {
    "typescript": "^5.9.0",
    "vitest": "^3.2.0",
    "@playwright/test": "^1.55.0",
    "eslint": "^9.36.0"
  }
}

(Số phiên bản ở trên chỉ để minh họa; dự án thật sẽ có con số khác.)

Ba khối cần hiểu:

scripts: sổ lệnh tắt của dự án. Thay vì nhớ lệnh dài, bạn gõ npm run <tên>.
dependencies (phụ thuộc): thư viện mà ứng dụng cần khi chạy thật, như Next.js, React, Zod.
devDependencies (phụ thuộc phát triển): thư viện chỉ cần khi làm việc (kiểm thử, kiểm tra kiểu, kiểm tra code), không cần khi khách dùng.

Ký hiệu ^ trước số phiên bản nghĩa là “chấp nhận các bản cập nhật không phá vỡ tương thích” theo quy ước đánh số phiên bản ngữ nghĩa (semantic versioning: CHÍNH.PHỤ.VÁ). ^16.0.0 cho phép 16.1.0, 16.2.3, nhưng không cho phép 17.0.0. Chi tiết ở bài Phát hành, rollback và đánh số phiên bản10-08.

Các script bạn sẽ dùng hằng ngày

Lệnh	Làm gì	Khi nào dùng
`npm run dev`	Chạy ứng dụng ở chế độ phát triển, thường tại `http://localhost:3000`; sửa code là trang tự cập nhật	Khi đang làm và xem thử
`npm run build`	Kiểm tra và đóng gói ứng dụng thành bản tối ưu để chạy thật	Trước khi triển khai; nếu build lỗi thì không được triển khai
`npm start`	Chạy bản đã build	Chạy thử bản giống production trên máy
`npm test`	Chạy kiểm thử tự động	Sau mỗi thay đổi; agent nên tự chạy và báo kết quả
`npm run lint`	Kiểm tra code có vi phạm quy tắc viết code không	Trước khi commit
`npm run typecheck`	Kiểm tra lỗi kiểu TypeScript	Trước khi commit

node_modules, lockfile và phụ thuộc

Trình quản lý gói: người đi chợ

Trình quản lý gói (package manager) là công cụ đọc danh sách nguyên liệu trong package.json, đi “chợ” (kho gói công khai như npm registry), mua về và xếp vào kho. Phổ biến nhất là npm (đi kèm Node.js); ngoài ra có pnpm, yarn, bun. Chúng làm cùng một việc, khác nhau ở tốc độ và cách tổ chức kho.

Vuốt ngang để xem hết sơ đồ

lần sau cài đúng y hệt

package.json
danh sách nguyên liệu
(next ^16, zod ^4…)

npm install
đi chợ

Kho gói công khai
npm registry

node_modules/
kho nguyên liệu
(hàng nghìn thư mục)

package-lock.json
biên nhận: phiên bản chính xác
của từng gói

npm run dev / build / test

Vuốt ngang để xem hết sơ đồ

lần sau cài đúng y hệt

package.json
danh sách nguyên liệu
(next ^16, zod ^4…)

npm install
đi chợ

Kho gói công khai
npm registry

node_modules/
kho nguyên liệu
(hàng nghìn thư mục)

package-lock.json
biên nhận: phiên bản chính xác
của từng gói

npm run dev / build / test

Hình 1 Sơ đồ luồng

Đọc sơ đồ dạng chữ

package.json danh sách nguyên liệu (next ^16, zod ^4…) → npm install đi chợ
Kho gói công khai npm registry → npm install đi chợ
npm install đi chợ → node_modules/ kho nguyên liệu (hàng nghìn thư mục)
npm install đi chợ → package-lock.json biên nhận: phiên bản chính xác của từng gói
node_modules/ kho nguyên liệu (hàng nghìn thư mục) → npm run dev / build / test

Các lệnh hay gặp:

Việc	npm	pnpm
Cài mọi thứ theo danh sách	`npm install`	`pnpm install`
Cài đúng theo lockfile (dùng trong CI)	`npm ci`	`pnpm install --frozen-lockfile`
Thêm một thư viện	`npm install zod`	`pnpm add zod`
Thêm thư viện chỉ dùng khi phát triển	`npm install -D vitest`	`pnpm add -D vitest`
Chạy script	`npm run dev`	`pnpm dev`
Chạy một công cụ không cần cài	`npx <tên>`	`pnpm dlx <tên>`

node_modules: kho nguyên liệu khổng lồ

Thư mục node_modules chứa mọi thư viện đã tải. Nó rất lớn, thường hàng trăm MB, vì mỗi thư viện lại phụ thuộc vào thư viện khác. Bạn cài 6 thư viện, nhưng chúng kéo theo hàng trăm thư viện con. Đây gọi là phụ thuộc bắc cầu (transitive dependencies).

Hai quy tắc về node_modules:

Không đưa vào Git (đã có trong .gitignore). Ai cần thì tự chạy npm install.
Có thể xóa và cài lại bất cứ lúc nào. “Xóa node_modules rồi cài lại” là cách sửa lỗi kinh điển khi thư viện bị hỏng.

Lockfile: biên nhận lô hàng

package.json nói “cần bột mì loại 11, từ phiên bản 16 trở lên”. Nhưng hôm nay mua có thể là lô 16.0.1, tháng sau là 16.2.0. Hai máy cài ở hai thời điểm có thể có nguyên liệu khác nhau, và “máy tôi chạy được, máy anh lỗi” bắt đầu từ đây.

Lockfile (package-lock.json với npm, pnpm-lock.yaml với pnpm, yarn.lock với yarn) là biên nhận ghi chính xác từng gói, từng phiên bản, kể cả gói con, đã được cài. Có lockfile, mọi máy (máy bạn, máy freelancer, server CI, server production) đều cài y hệt nhau.

Quy tắc về lockfile:

Luôn đưa lockfile vào Git.
Chỉ dùng một trình quản lý gói cho một dự án. Thấy cả package-lock.json lẫn pnpm-lock.yaml là dấu hiệu lộn xộn.
Không sửa tay lockfile. Khi agent thay đổi lockfile, nghĩa là thư viện đã được thêm, xóa hoặc nâng cấp; hãy xem package.json đổi gì.

Áp dụng vào dự án Bánh Mộc

Nhật ký công trình · Bánh Mộc

BM-261012-012

12.10.2026

Chị LanChủ chuỗi

Chị Lan dừng tay trước khi duyệt lệnh agent xin chạy, cạnh bảng phân loại lệnh an toàn

Lần đầu chị Lan cùng agent tải dự án banhmoc-oms về máy, chị gặp ba tình huống và xử lý được nhờ bài này.

Tình huống 1: “command not found”. Agent đề nghị chạy npm install. Terminal báo zsh: command not found: npm. Chị hiểu ngay: máy chưa có Node.js, giống bếp chưa có điện. Chị cài Node.js theo hướng dẫn chính thức, mở lại terminal, gõ node -v thấy hiện số phiên bản, rồi chạy lại.

Tình huống 2: Đứng sai chỗ. Chạy npm run dev, terminal báo không tìm thấy package.json. Chị gõ pwd và thấy mình đang ở ~/Downloads, không phải ~/projects/banhmoc-oms. Một lệnh cd ~/projects/banhmoc-oms là xong. Ứng dụng chạy tại http://localhost:3000.

Tình huống 3: Duyệt lệnh của agent. Khi làm tính năng xuất báo cáo, agent xin chạy npm install excel-export-helper-vn. Chị nhớ cảnh báo về thư viện lạ, nên hỏi lại agent. Agent kiểm tra và thừa nhận không chắc thư viện đó tồn tại; nó đề xuất dùng một thư viện phổ biến, có tài liệu chính thức thay thế. Chị đồng ý, rồi nhìn package.json thấy đúng một dòng mới trong dependencies, còn lockfile thay đổi rất nhiều dòng, đúng như dự đoán vì thư viện kéo theo các gói con.

Cuối buổi, chị thêm vào file AGENTS.md của dự án:

MARKDOWN

## Lệnh dự án
- Cài đặt: npm install (chỉ dùng npm, không dùng pnpm/yarn)
- Chạy thử: npm run dev
- Kiểm chứng trước khi báo xong: npm run typecheck && npm run lint && npm test && npm run build
- Hỏi ý kiến trước khi thêm thư viện mới; nêu lý do và trang chính thức của thư viện.

Prompt mẫu

Prompt 1: giải thích lệnh trước khi chạy.

Trước khi chạy bất kỳ lệnh terminal nào có thể thay đổi hoặc xóa file, cài/gỡ thư viện,
hay động tới Git, hãy giải thích bằng một câu tiếng Việt: lệnh làm gì, ảnh hưởng tới
những file/thư mục nào, và có hoàn tác được không. Chờ tôi xác nhận rồi mới chạy.

Prompt 2: đọc hiểu cấu trúc một dự án mới.

Tôi là người không chuyên. Hãy đọc cấu trúc thư mục và package.json của dự án này, rồi giải thích:
1. Dự án dùng ngôn ngữ, framework, trình quản lý gói nào?
2. Các script trong package.json làm gì, script nào để chạy thử, kiểm thử, build?
3. Thư mục nào chứa code nghiệp vụ chính, thư mục nào là cấu hình, thư mục nào sinh tự động?
4. Để chạy dự án lần đầu trên máy tôi, cần những bước nào?
Trình bày ngắn gọn, dạng danh sách.

Prompt 3: thẩm định thư viện trước khi thêm.

Bạn đề xuất thêm thư viện [tên]. Trước khi cài, hãy cho tôi biết: thư viện này giải quyết
việc gì; có thể tự viết đoạn code ngắn thay thế không; tên gói chính xác trên npm và
trang tài liệu chính thức; mức độ phổ biến và tình trạng bảo trì (nếu bạn không chắc,
hãy nói là không chắc và kiểm tra bằng lệnh npm view). Chỉ cài sau khi tôi đồng ý.

Sai lầm thường gặp

Sự cố 01

Sợ terminal nên giao toàn quyền cho agent.

Triệu chứng

Bật chế độ “tự chạy mọi lệnh” vì không muốn đọc. Một lệnh xóa nhầm là mất công nhiều ngày.

Cách tránh

Giữ chế độ xin phép cho lệnh thay đổi; cho phép sẵn các lệnh chỉ đọc và lệnh kiểm chứng (test, lint, build).
Sự cố 02

Chạy lệnh ở sai thư mục.

Triệu chứng

Lệnh báo không tìm thấy file, hoặc tệ hơn, thao tác lên nhầm thư mục.

Cách tránh

Tập thói quen gõ pwd trước các lệnh quan trọng; dùng terminal tích hợp trong editor để nó tự mở đúng thư mục dự án.
Sự cố 03

Đưa node_modules hoặc .env.local vào Git.

Triệu chứng

Repo phình to hàng trăm MB, hoặc tệ hơn, lộ bí mật.

Cách tránh

Kiểm tra .gitignore có node_modules, .next, .env*.local ngay khi khởi tạo dự án.
Sự cố 04

Không commit lockfile, hoặc trộn nhiều trình quản lý gói.

Triệu chứng

Mỗi máy cài một kiểu, lỗi “máy tôi chạy được” xuất hiện.

Cách tránh

Chọn một trình quản lý gói, ghi vào AGENTS.md, luôn commit lockfile tương ứng.
Sự cố 05

Cài thư viện AI đề xuất mà không kiểm tra.

Triệu chứng

Thư viện bịa, thư viện bỏ hoang, hoặc thư viện nặng chỉ để làm một việc nhỏ.

Cách tránh

Dùng Prompt mẫu 3; ưu tiên thư viện đã có trong dự án hoặc tự viết đoạn ngắn.

Checklist

Tôi mở được terminal và biết shell mình đang dùng (zsh, bash hay PowerShell).
Tôi dùng được 10 lệnh cơ bản và các phím Tab, mũi tên lên, Ctrl + C.
Tôi phân biệt đường dẫn tuyệt đối và tương đối; hiểu ~, ., ...
Tôi nhận ra lệnh nguy hiểm (rm -rf, --force, reset --hard) khi agent xin chạy.
Tôi đọc được scripts, dependencies, devDependencies trong package.json.
Tôi hiểu vì sao commit lockfile nhưng không commit node_modules.
Dự án của tôi chỉ dùng một trình quản lý gói.
AGENTS.md ghi rõ lệnh cài đặt, chạy thử và kiểm chứng.

Bài tập thực hành

Bài 1

Cơ bản

Dạo quanh máy bằng terminal

Mở terminal. Gõ pwd để biết mình ở đâu. Tạo thư mục thu-terminal, đi vào đó, tạo file ghi-chu.md, liệt kê file, đổi tên thành ghi-chu-moi.md, lùi ra ngoài, rồi xóa cả thư mục (dùng lệnh xóa thư mục phù hợp hệ điều hành của bạn).

Kết quả mong đợi

Bạn hoàn thành chuỗi thao tác mà không cần mở trình quản lý file, và hiểu vì sao lệnh xóa thư mục cần cẩn thận.
Bài 2

Cơ bản

Đọc package.json của một dự án thật

Vào trang GitHub của một dự án mã nguồn mở viết bằng JavaScript/TypeScript bất kỳ, mở file package.json. Liệt kê các script, đoán xem mỗi script làm gì, và đếm số thư viện trong dependencies và devDependencies.

Kết quả mong đợi

Bạn nhận ra hầu hết dự án đều có các script dev, build, test, lint với tên tương tự.
Bài 3

Nâng cao

Phân loại lệnh của agent

Cho danh sách lệnh sau, xếp vào ba mức (vô hại, cần đọc kỹ, nguy hiểm): git status, npm install date-fns, rm -rf node_modules, rm -rf src, npm test, git push --force, cat .env.local, npx drizzle-kit migrate.

Kết quả mong đợi

Vô hại: git status, npm test. Cần đọc kỹ: npm install date-fns (thêm phụ thuộc), rm -rf node_modules (xóa nhưng tải lại được). Nguy hiểm: rm -rf src, git push --force. Đặc biệt lưu ý: cat .env.local tuy chỉ đọc nhưng đưa bí mật vào ngữ cảnh của agent (xem bài 01-08); lệnh migrate thay đổi cấu trúc database, phải biết đang trỏ tới database nào.

Thuật ngữ trong bài

Terminal / dòng lệnh: Cửa sổ nói chuyện với máy bằng câu lệnh chữ
Shell: Chương trình hiểu lệnh: zsh, bash, PowerShell
Flag / tùy chọn: Phần điều chỉnh cách lệnh chạy, ví dụ -r
Đường dẫn tuyệt đối: Địa chỉ đầy đủ từ gốc ổ đĩa
Đường dẫn tương đối: Chỉ đường tính từ vị trí hiện tại
Trình quản lý gói: Công cụ tải và quản lý thư viện: npm, pnpm, yarn, bun
package.json: Hồ sơ dự án: tên, script, danh sách phụ thuộc
Phụ thuộc (dependency): Thư viện bên ngoài mà dự án cần
devDependency: Thư viện chỉ cần khi phát triển
Phụ thuộc bắc cầu: Thư viện con mà thư viện bạn dùng lại cần
node_modules: Thư mục chứa thư viện đã tải về
Lockfile: File ghi chính xác phiên bản mọi gói đã cài
Script: Lệnh tắt định nghĩa trong package.json
npx: Chạy một công cụ từ kho gói mà không cần cài cố định

Đọc thêm

Next.js Documentation: phần cài đặt và cấu trúc dự án.
Semantic Versioning: quy ước đánh số phiên bản.
Thiết lập môi trường làm việc: editor, Node.js, Git và coding agent06-01
Khởi tạo dự án đúng cách: khung dự án, cấu trúc và AGENTS.md06-02
An toàn chuỗi cung ứng phần mềm09-05

Nghiệm thu tờ 01-06

Đọc xong và tự kiểm theo phiếu nghiệm thu, rồi đánh dấu tờ này.

Tác giả

Phú Digital

Đội ngũ PDL Digital — triển khai website, giải pháp AI và digital marketing cho doanh nghiệp.

Terminal, thư mục dự án và trình quản lý gói: làm quen không sợ hãi

Bạn sẽ học được gì

Terminal là gì và vì sao bạn cần nó

Vì sao người không lập trình cần học terminal?

Cấu trúc một câu lệnh

10 lệnh terminal cơ bản

Lệnh nào an toàn, lệnh nào cần cân nhắc khi agent xin quyền

Đường dẫn tuyệt đối và tương đối

Đọc lỗi terminal thường gặp

Cấu trúc một dự án: đọc cây thư mục

package.json: danh sách nguyên liệu và sổ lệnh

Các script bạn sẽ dùng hằng ngày

node_modules, lockfile và phụ thuộc

Trình quản lý gói: người đi chợ

node_modules: kho nguyên liệu khổng lồ

Lockfile: biên nhận lô hàng

Áp dụng vào dự án Bánh Mộc

Prompt mẫu

Prompt 1: giải thích lệnh trước khi chạy.

Prompt 2: đọc hiểu cấu trúc một dự án mới.

Prompt 3: thẩm định thư viện trước khi thêm.

Sai lầm thường gặp

Sợ terminal nên giao toàn quyền cho agent.

Chạy lệnh ở sai thư mục.

Đưa node_modules hoặc .env.local vào Git.

Không commit lockfile, hoặc trộn nhiều trình quản lý gói.

Cài thư viện AI đề xuất mà không kiểm tra.

Checklist

Bài tập thực hành

Dạo quanh máy bằng terminal

Đọc package.json của một dự án thật

Phân loại lệnh của agent

Thuật ngữ trong bài

Đọc thêm

Muốn dựng phần mềm riêng cho doanh nghiệp của bạn?

Vì sao người không lập trình cần học terminal?

Lệnh nào an toàn, lệnh nào cần cân nhắc khi agent xin quyền

Các script bạn sẽ dùng hằng ngày

Trình quản lý gói: người đi chợ

node_modules: kho nguyên liệu khổng lồ

Lockfile: biên nhận lô hàng

Prompt 1: giải thích lệnh trước khi chạy.

Prompt 2: đọc hiểu cấu trúc một dự án mới.

Prompt 3: thẩm định thư viện trước khi thêm.

Sợ terminal nên giao toàn quyền cho agent.

Chạy lệnh ở sai thư mục.

Đưa node_modules hoặc .env.local vào Git.

Không commit lockfile, hoặc trộn nhiều trình quản lý gói.

Cài thư viện AI đề xuất mà không kiểm tra.

Dạo quanh máy bằng terminal

Đọc package.json của một dự án thật

Phân loại lệnh của agent

Muốn dựng phần mềm riêng cho doanh nghiệp của bạn?

Nhận tư vấn miễn phí

Nhận tư vấn
miễn phí