Sao lưu cấu hình Claude Code: giữ gì, bỏ gì

Theo thời gian, thiết lập Claude Code của tôi không còn là mặc định nữa. Tôi tinh chỉnh settings, viết một script status line, thêm hook, bỏ vào vài skill, và nuôi lớn một file CLAUDE.md toàn cục đầy thói quen. Không thứ nào trong số đó nằm trong app — chúng là một đống file trong ~/.claude. Mất thư mục đó thì tôi không mất Claude Code; tôi mất Claude Code của tôi. Bài này nói về việc sao lưu nó: vì sao đáng làm, file nào thật sự quan trọng, và một file bạn tuyệt đối không được sao chép đi đâu cả.

Vì sao phải sao lưu

Cấu hình nằm trong một thư mục trên một máy. Điều đó mong manh theo vài cách:

Máy mới, làm lại từ đầu. Dựng một laptop mới và bạn bắt đầu với ~/.claude trống trơn. Không có bản sao lưu, bạn phải dựng lại mọi setting, hook, và script từ trí nhớ.
Giữ hai máy đồng bộ. Laptop công ty, desktop ở nhà — bạn muốn cùng một status line và cùng thói quen trên cả hai. Bản sao lưu là thứ bạn đồng bộ từ đó.
Khôi phục một chỉnh sửa hỏng. Bạn sửa settings.json, có gì đó vỡ, và bạn không nhớ trước đó nó trông thế nào. Nếu bản sao lưu nằm trong git, phiên bản cũ chỉ cách một git diff.
Lịch sử và rà soát. Một khi cấu hình nằm trong repo, mỗi thay đổi là một commit. Bạn thấy được lúc nào mình thêm một hook và vì sao, và lùi lại nếu nó giở chứng.

Cách sửa thì nhỏ: sao chép các file tự tay soạn tới một nơi an toàn — tôi dùng một repo git riêng tư — và commit. Mẹo nằm ở chỗ biết file nào, vì ~/.claude phần lớn là thứ bạn nên để lại phía sau.

Cái gì thật sự cần sao lưu

Chỉ một số ít thứ trong ~/.claude là của bạn theo nghĩa quan trọng — bạn viết ra chúng, và bạn sẽ phải viết lại. Đây là những gì script sao lưu của tôi sao chép, và mỗi cái là gì:

CLAUDE.md — bộ nhớ toàn cục của tôi: văn phong, quy tắc an toàn git, định dạng commit. Những hướng dẫn Claude đọc trong mọi dự án.
settings.json — cấu hình chính: quyền hạn, hook, lệnh status line, lựa chọn model và theme, các plugin đã bật. Trái tim của thiết lập.
statusline.sh — script status line tùy chỉnh của tôi (cái từ bài trước). settings.json trỏ tới nó, nên hai thứ đi cùng nhau.
file-suggestion.sh — một script phụ mà settings.json gọi để gợi ý file. Lại một cặp kiểu "settings trỏ tới một script".
hooks/ — các script mà hook của tôi chạy (như cái "gác cổng" âm thanh báo xong). Cấu hình hook trong settings.json vô dụng nếu thiếu các file này.
skills/ — các skill tùy chỉnh của tôi. Tự tay dựng, nên đáng giữ.
commands/ — các slash command tùy chỉnh, nếu bạn có. Cũng vậy: của bạn, mất thì viết lại.

Trong script sao lưu của tôi (rsync.sh), đó là một danh sách các lệnh sao chép đơn giản vào một thư mục repo:

REPO=~/workspace/config

rsync -av --mkpath ~/.claude/CLAUDE.md          "$REPO/.claude/CLAUDE.md"
rsync -av --mkpath ~/.claude/settings.json      "$REPO/.claude/settings.json"
rsync -av --mkpath ~/.claude/statusline.sh      "$REPO/.claude/statusline.sh"
rsync -av --mkpath ~/.claude/file-suggestion.sh "$REPO/.claude/file-suggestion.sh"
rsync -av --mkpath ~/.claude/hooks/             "$REPO/.claude/hooks/"
rsync -av --mkpath ~/.claude/skills/            "$REPO/.claude/skills/"

rsync -av sao chép đệ quy và giữ nguyên quyền (nên statusline.sh vẫn chạy được); --mkpath tạo thư mục đích nếu chưa có. Sau khi sao chép, một git commit trong repo ghi lại thay đổi.

Cả các file theo dự án nữa

Cấu hình không chỉ có ở cấp toàn cục. Mỗi dự án có thể có CLAUDE.md riêng (dùng chung) và CLAUDE.local.md riêng (cá nhân), cùng các file .env của nó. Những cái đó đáng sao lưu trong cùng một lượt. Vì mẫu này lặp lại qua nhiều repo, tôi viết hai hàm phụ nhỏ thay vì sao-chép-dán:

# Sao chép CLAUDE.md và CLAUDE.local.md từ một dự án vào repo sao lưu.
sync_claude() {
  local src="$1" dest="$2" f
  shopt -s nullglob
  for f in "$src"/CLAUDE.md "$src"/CLAUDE.local.md; do
    rsync -av --mkpath "$f" "$dest/$(basename "$f")"
  done
  shopt -u nullglob
}

# Sao chép mọi file .env / .*.env từ một dự án vào repo sao lưu.
sync_envs() {
  local src="$1" dest="$2" f
  shopt -s nullglob
  for f in "$src"/.env "$src"/.*.env; do
    rsync -av --mkpath "$f" "$dest/$(basename "$f")"
  done
  shopt -u nullglob
}

Rồi mỗi dự án một dòng: sync_claude ~/workspace/some/project "$REPO/.../project". nullglob khiến vòng lặp bỏ qua gọn gàng khi một dự án không có file như thế, thay vì cố sao chép một tên file không tồn tại.

Cái gì để lại — và vì sao

Phần lớn ~/.claude không đáng sao lưu, và sao chép chúng sẽ khiến bản sao lưu to, ồn, và chậm. Bỏ qua những cái này:

projects/ — bản ghi phiên theo dự án và những ghi chú Claude tự viết cho mình. To, riêng của máy, và được tạo lại khi bạn làm việc. Đây là phần cồng kềnh nhất của thư mục.
sessions/, shell-snapshots/, history.jsonl, file-history/ — trạng thái phiên và lịch sử. Là runtime cục bộ, không phải cấu hình.
cache/, paste-cache/, stats-cache.json, downloads/, daemon/, ide/, jobs/, tasks/ — cache và vùng nháp runtime. Đều được tạo lại.
plugins/ — các plugin đã cài. Chúng cài lại được; settings.json đã ghi bạn bật những cái nào.
backups/, settings.json.bak, .last-* — các bản sao lưu cục bộ và sổ sách của chính app.

Quy tắc chung: sao lưu thứ bạn tự tay viết; bỏ qua thứ app tạo ra. Nếu mất một file chỉ tốn của bạn một lần tải lại hay một cache được dựng lại, nó không thuộc về bản sao lưu.

Một file bạn tuyệt đối không được sao lưu

Có đúng một file trong ~/.claude vừa hấp dẫn để lấy (nó nhỏ) vừa nguy hiểm để sao chép:

~/.claude/.credentials.json

Đây là token đăng nhập của bạn. Sao chép nó vào một repo git là bạn đã đưa một chiếc chìa khóa còn sống của tài khoản vào lịch sử — nơi nó có thể rò rỉ, đồng bộ lên remote, hoặc rơi vào một bản clone. Để ý rằng nó vắng mặt ở mọi dòng trong script sao lưu của tôi. Đó là cố ý. Bạn chẳng bao giờ cần nó trong bản sao lưu: trên máy mới bạn chỉ việc đăng nhập một lần và Claude Code viết ra một cái mới.

Quy tắc rộng hơn: bí mật chỉ nằm trong một kho riêng tư, và token còn sống thì không đưa vào chút nào. Repo sao lưu của tôi là riêng tư, đó là lý do duy nhất nó được phép chứa các file .env — nhưng kể cả trong một repo riêng tư, thông tin đăng nhập tài khoản vẫn ở ngoài. Nếu bản sao lưu của bạn có bất kỳ khả năng nào trở thành công khai hay dùng chung, hãy giữ mọi bí mật ra khỏi nó.

Khôi phục trên máy mới

Vì bản sao lưu chỉ là các file trong một repo, khôi phục là sao chép theo chiều ngược lại: clone repo trên máy mới và rsync thư mục .claude về đúng chỗ.

git clone <repo-cau-hinh-rieng-tu-cua-ban> ~/workspace/config
rsync -av ~/workspace/config/.claude/ ~/.claude/
# rồi đăng nhập một lần để tạo một ~/.claude/.credentials.json mới

Settings, status line, hook, và skill đáp xuống đúng chỗ cũ. Bạn đăng nhập một lần, và bạn trở lại với Claude Code của bạn — không phải cái mặc định.

Một checklist để lấy dùng

Sao lưu các file tự tay soạn: CLAUDE.md, settings.json, statusline.sh, file-suggestion.sh, hooks/, skills/, và commands/.
Sao lưu CLAUDE.md / CLAUDE.local.md theo dự án và các file .env nếu bạn muốn khôi phục đầy đủ.
Bỏ qua những thứ được tạo ra: projects/, sessions/, cache, plugins/, và thư mục backups/ của chính app.
Đừng bao giờ sao chép ~/.claude/.credentials.json — hãy đăng nhập lại từ đầu.
Giữ bản sao lưu riêng tư, và để nó trong git để mỗi thay đổi là một commit rà soát được.

Thiết lập Claude Code của bạn là một thứ nhỏ mà quý giá, bạn bồi đắp lặng lẽ qua nhiều tháng. Một tá dòng rsync và một repo git nghĩa là bạn không bao giờ phải dựng lại nó lần thứ hai.

Link tham khảo

Bài viết gốc (tiếng Anh): Backing Up Your Claude Code Config: What to Keep, What to Skip

Claude