Thư mục .claude

Claude Code đọc tài liệu hướng dẫn (instruction), các cấu hình(settings), skill, subagent, và memory từ thư mục dự án của bạn và từ ~/.claude trong thư mục home (của máy tính). Commit các file trong dự án vào git để chia sẻ với cả team; các file trong ~/.claude (ở thư mục home của máy tính) là cấu hình cá nhân, áp dụng cho mọi dự án.

Trên Windows, ~/.claude tương ứng với %USERPROFILE%\.claude. Nếu bạn đặt biến môi trường CLAUDE_CONFIG_DIR, mọi đường dẫn ~/.claude trên trang này sẽ nằm dưới thư mục đó thay vì mặc định.

Phần lớn người dùng chỉ cần sửa CLAUDE.md và settings.json. Phần còn lại của thư mục là tuỳ chọn - thêm skill, rule, hay subagent chỉ khi thực sự cần.

Cấu trúc thư mục dự án

Bấm vào một file bên trái để xem mô tả chi tiết bên phải; bấm vào thư mục để thu gọn/mở rộng.

Bấm vào một file bên trái để xem chi tiết.

Cấu trúc thư mục cá nhân (`~/.claude/`)

Bấm vào một file bên trái để xem chi tiết.

Những gì không nằm trong hai cây trên

Một vài file liên quan sống ở nơi khác:

File	Vị trí	Mục đích
`managed-settings.json`	Cấp hệ thống, tuỳ hệ điều hành	Settings do tổ chức áp đặt, bạn không ghi đè được (trừ vài ngoại lệ hẹp) - xem Server-managed settings.
`CLAUDE.local.md`	Gốc dự án	Sở thích riêng cho dự án này, nạp cùng `CLAUDE.md`. Tự tạo và thêm vào `.gitignore`.
Plugin đã cài	`~/.claude/plugins`	Marketplace đã clone, phiên bản plugin đã cài, dữ liệu riêng từng plugin, quản lý bằng các lệnh `claude plugin`.

~/.claude còn chứa dữ liệu Claude Code tự ghi ra khi bạn làm việc: transcript, lịch sử prompt, snapshot file, cache, và log - xem phần Dữ liệu ứng dụng bên dưới.

Chọn đúng file để sửa

Bạn muốn…	Sửa file	Phạm vi	Xem thêm
Cho Claude biết ngữ cảnh và quy ước dự án	`CLAUDE.md`	dự án hoặc cá nhân	Bộ nhớ
Cho phép/chặn một tool hoặc lệnh cụ thể	`settings.json` → `permissions` hoặc `hooks`	dự án hoặc cá nhân	Permissions, Hooks
Chạy script trước/sau khi Claude dùng tool	`settings.json` → `hooks`	dự án hoặc cá nhân	Hooks
Đặt biến môi trường cho phiên	`settings.json` → `env`	dự án hoặc cá nhân	Settings
Giữ tuỳ biến cá nhân ngoài git	`settings.local.json`	chỉ dự án này	Settings
Thêm prompt/khả năng gọi bằng `/tên`	`skills/<tên>/SKILL.md`	dự án hoặc cá nhân	Skills
Định nghĩa subagent chuyên biệt	`agents/*.md`	dự án hoặc cá nhân	Subagents
Điều phối nhiều subagent bằng script	`workflows/*.js`	dự án hoặc cá nhân	Dynamic workflows
Kết nối công cụ ngoài qua MCP	`.mcp.json`	chỉ dự án	MCP
Đổi cách Claude định dạng câu trả lời	`output-styles/*.md`	dự án hoặc cá nhân	Output styles

Bảng tra toàn bộ file

Các file phạm vi dự án nằm trong repo dưới .claude/ (hoặc ở gốc dự án với CLAUDE.md, .mcp.json, .worktreeinclude). Các file phạm vi cá nhân (global) nằm trong ~/.claude/ và áp dụng cho mọi dự án.

Vài thứ có thể ghi đè lên những gì bạn đặt trong các file này:

Managed settings do tổ chức triển khai luôn thắng, trừ các ngoại lệ nêu trong thứ tự ưu tiên settings.
CLI flag như --permission-mode hay --settings ghi đè settings.json cho phiên đó.
Một số biến môi trường thắng cả setting tương ứng - tuỳ biến, kiểm tra từng biến trong Tra cứu biến môi trường.

File	Phạm vi	Commit?	Tác dụng
`CLAUDE.md`	Dự án & cá nhân	✓	Chỉ dẫn nạp mỗi phiên
`rules/*.md`	Dự án & cá nhân	✓	Chỉ dẫn theo chủ đề, có thể giới hạn theo đường dẫn
`settings.json`	Dự án & cá nhân	✓	Permissions, hooks, biến môi trường, model mặc định
`settings.local.json`	Chỉ dự án	Gitignore tự động khi Claude Code ghi vào	Ghi đè cá nhân
`.mcp.json`	Chỉ dự án	✓	MCP server dùng chung cả team
`.worktreeinclude`	Chỉ dự án	✓	Danh sách file gitignored cần copy khi tạo worktree mới
`skills/<tên>/SKILL.md`	Dự án & cá nhân	✓	Prompt tái sử dụng, gọi bằng `/tên` hoặc tự động kích hoạt
`commands/*.md`	Dự án & cá nhân	✓	Prompt một-file - cùng cơ chế với skill
`output-styles/*.md`	Dự án & cá nhân	✓	Đoạn system-prompt tuỳ biến
`agents/*.md`	Dự án & cá nhân	✓	Định nghĩa subagent, có prompt và tool riêng
`workflows/*.js`	Dự án & cá nhân	✓	Script dynamic workflow do Claude viết, lưu từ `/workflows`; mỗi file trở thành một lệnh `/<tên>`
`agent-memory/<tên>/`	Dự án & cá nhân	✓	Bộ nhớ bền vững riêng của từng subagent
`~/.claude.json`	Chỉ global	-	Trạng thái app, OAuth, toggle giao diện, MCP server cá nhân
`projects/<dự-án>/memory/`	Chỉ global	-	Auto memory - ghi chú của Claude cho chính nó qua các phiên
`keybindings.json`	Chỉ global	-	Phím tắt tuỳ biến
`themes/*.json`	Chỉ global	-	Theme màu tuỳ biến

Xử lý sự cố cấu hình

Nếu một setting, hook, hay file không có tác dụng, xem Debug cấu hình của bạn để có lệnh kiểm tra và bảng tra theo triệu chứng.

Dữ liệu ứng dụng

Ngoài cấu hình do bạn viết, ~/.claude còn chứa dữ liệu Claude Code ghi ra trong lúc làm việc. Các file này đều là plaintext. Bất cứ thứ gì đi qua một tool đều được ghi vào transcript trên đĩa: nội dung file, output lệnh, văn bản bạn paste.

Tự động dọn dẹp

Claude Code xoá các đường dẫn dưới đây khi chúng cũ hơn cleanupPeriodDays, miễn là có thể xác định an toàn thời gian lưu giữ. Mặc định là 30 ngày, tối thiểu 1 ngày; đặt 0 sẽ báo lỗi validation. Cùng ngưỡng tuổi này cũng áp dụng cho việc tự động dọn các worktree bị bỏ quên.

Đường dẫn dưới `~/.claude/`	Nội dung
`projects/<dự-án>/<session>.jsonl`	Transcript đầy đủ: mọi message, tool call, kết quả tool
`projects/<dự-án>/<session>/subagents/`	Transcript hội thoại của subagent, xoá cùng transcript phiên cha
`projects/<dự-án>/<session>/tool-results/`	Output tool lớn được tách ra file riêng
`file-history/<session>/`	Snapshot file trước khi sửa, dùng cho checkpoint restore. Giữ 100 checkpoint gần nhất
`plans/`	File plan được viết trong plan mode
`debug/`	Log debug từng phiên, chỉ ghi khi chạy `--debug` hoặc `/debug`
`paste-cache/`, `image-cache/`	Nội dung đoạn paste lớn và ảnh đính kèm
`session-env/`	Metadata môi trường của từng phiên
`tasks/`	Danh sách task từng phiên, do task tool ghi ra
`shell-snapshots/`	Alias, function, tuỳ chọn shell được ghi lại lúc khởi động và áp dụng cho mỗi lệnh Bash tool chạy. Xoá khi thoát sạch
`backups/`	Bản sao `~/.claude.json` có timestamp, chụp trước khi migrate config
`feedback-bundles/`	Transcript đã ẩn thông tin nhạy cảm, ghi bởi `/feedback` khi dùng provider bên thứ ba hoặc chưa cấu hình Anthropic credential
`usage-data/`	`report.html` và các bản báo cáo có timestamp do `/insights` ghi ra, cùng dữ liệu phân tích cache dùng để tạo báo cáo
`todos/`, `statsig/`, `logs/`	Thư mục cũ từ phiên bản trước, không còn được ghi vào

Có bốn ngoại lệ không nằm trong đợt dọn tự động này:

sessions/: mỗi phiên đang chạy giữ một file nhỏ, dùng để phát hiện phiên chạy đồng thời và crash. Không thuộc đợt dọn theo tuổi - Claude Code xoá từng file khi phiên thoát và dọn phần sót lại sau crash ở lần khởi động kế tiếp.
Auto memory: thư mục projects/<dự-án>/memory/ được loại khỏi đợt dọn này, và chỉ bị xoá sau khi rỗng suốt cả thời gian lưu giữ.
Bare mode: khi chạy claude -p với --bare, Claude Code không chạy đợt dọn trong phiên đó.
Tạm dừng dọn: nếu Claude Code không xác định an toàn được thời gian lưu giữ, nó tạm dừng đợt dọn và hiện cảnh báo trong /status cho đến khi bạn sửa lỗi cấu hình.

Giữ lại cho đến khi bạn tự xoá

Các đường dẫn sau không nằm trong đợt dọn tự động và tồn tại vô thời hạn:

Đường dẫn dưới `~/.claude/`	Nội dung
`history.jsonl`	Mọi prompt bạn từng gõ, kèm timestamp và đường dẫn dự án - dùng cho phím `↑`
`stats-cache.json`	Số liệu token và chi phí tổng hợp hiển thị bởi `/usage`
`remote-settings.json`	Bản cache của server-managed settings tổ chức bạn (nếu có cấu hình), làm mới mỗi lần khởi động
`cache/changelog.md`	Bản cache changelog Claude Code, dùng hiện release note sau khi cập nhật
`policy-limits.json`	Cache policy giới hạn tính năng của tổ chức (một số loại tài khoản)

Ngoài ra còn vài file cache/lock nhỏ khác tuỳ tính năng bạn dùng, xoá được an toàn.

Lưu trữ dạng plaintext

Transcript và lịch sử không được mã hoá khi lưu. Quyền hạn file của hệ điều hành là lớp bảo vệ duy nhất. Nếu một tool đọc file .env hay một lệnh in ra credential, giá trị đó sẽ được ghi vào projects/<dự-án>/<session>.jsonl. Để giảm rủi ro:

Giảm cleanupPeriodDays để transcript tự xoá sớm hơn.
Đặt biến môi trường CLAUDE_CODE_SKIP_PROMPT_HISTORY để bỏ ghi transcript và lịch sử prompt ở mọi chế độ. Ở chế độ non-interactive, dùng thêm --no-session-persistence cùng -p, hoặc đặt persistSession: false trong Agent SDK bản TypeScript (SDK Python chưa có tuỳ chọn tương đương).
Dùng permission rule để chặn đọc file chứa credential.

Dọn dữ liệu cục bộ

Chạy claude project purge để xoá toàn bộ trạng thái Claude Code lưu cho một dự án. Lệnh này xoá:

Transcript và auto memory dưới projects/
Các mục tasks/, debug/, file-history/ của từng phiên
Các dòng prompt khớp trong history.jsonl
Mục của dự án trong ~/.claude.json

Lệnh in ra đầy đủ kế hoạch xoá và hỏi xác nhận trước khi xoá bất cứ gì.

Xem trước kế hoạch mà không xoá thật:

claude project purge ~/work/my-repo --dry-run

Kế hoạch liệt kê từng mục khớp và lý do:

Purge plan for /home/user/work/my-repo:

  dir:    /home/user/.claude/projects/-home-user-work-my-repo
          project transcripts (.jsonl) and memory/
  config: projects["/home/user/work/my-repo"]
          project entry in ~/.claude.json (trust, history, MCP servers)
  filter: /home/user/.claude/history.jsonl
          12 prompt(s) typed in this project

shell-snapshots/ are not project-scoped and will not be touched
backups/ may still contain this project entry in old .claude.json snapshots (/home/user/.claude/backups); at most 5 are kept and they rotate out automatically

Dry run: 3 item(s) would be deleted.

Xoá thật, với một lần hỏi xác nhận:

claude project purge ~/work/my-repo

Lệnh in cùng kế hoạch, sau đó hỏi Delete 3 item(s) for /home/user/work/my-repo? This cannot be undone. [y/N] và chỉ xoá nếu bạn trả lời y.

Bỏ qua đường dẫn để chọn dự án từ danh sách tương tác. Bỏ qua luôn bước xác nhận (phù hợp cho script):

claude project purge ~/work/my-repo --yes

Dùng --all thay vì một đường dẫn cụ thể để purge trạng thái của mọi dự án cùng lúc - cách này xoá thẳng history.jsonl thay vì lọc từng dòng. Dùng -i để đi qua từng mục trong kế hoạch xoá một cách tuần tự.

Lệnh này không đụng đến shell-snapshots/ và backups/ vì chúng không gắn với một dự án cụ thể, và sẽ cảnh báo về điều đó trong kế hoạch xoá.

Bạn cũng có thể tự tay xoá bất kỳ đường dẫn dữ liệu ứng dụng nào ở trên. Phiên mới không bị ảnh hưởng. Bảng dưới đây cho biết bạn sẽ mất gì đối với các phiên cũ:

Xoá	Bạn mất
`~/.claude/projects/`	Resume, continue, rewind cho các phiên cũ, và auto memory của mọi dự án
`~/.claude/history.jsonl`	Gợi ý prompt cũ bằng phím `↑`
`~/.claude/paste-cache/`	Văn bản đã paste trong các prompt được gợi lại
`~/.claude/file-history/`	Checkpoint restore cho các phiên cũ
`~/.claude/stats-cache.json`	Tổng số liệu lịch sử hiển thị bởi `/usage`
`~/.claude/usage-data/`	Báo cáo `/insights` cũ và dữ liệu phân tích cache dùng để tạo chúng
`~/.claude/feedback-bundles/`	Feedback/bug report chưa gửi cho Anthropic
`~/.claude/remote-settings.json`, `~/.claude/cache/changelog.md`, `~/.claude/policy-limits.json`	Không mất gì - được tải lại tự động
`~/.claude/debug/`, `~/.claude/plans/`, `~/.claude/image-cache/`, `~/.claude/session-env/`, `~/.claude/tasks/`, `~/.claude/shell-snapshots/`, `~/.claude/backups/`	Không mất gì người dùng thấy được
`~/.claude/todos/`, `~/.claude/statsig/`, `~/.claude/logs/`	Không mất gì - thư mục cũ, phiên bản hiện tại không còn ghi vào

Tài nguyên liên quan

Bộ nhớ với CLAUDE.md - viết và tổ chức CLAUDE.md, rule, và auto memory
Settings - đặt permission, hook, biến môi trường, model mặc định
Skills - xây dựng prompt và workflow tái sử dụng
Subagents - định nghĩa agent chuyên biệt với ngữ cảnh riêng