Thông tin lưu ở đâu: cái gì lên git, cái gì riêng máy
Mỗi mẩu thông tin trên máy phải trả lời được ba câu: phạm vi dùng, lên git không và repo nào, mất máy dựng lại từ đâu. Ghi chú này cho khung 13 phạm vi, cây quyết định 8 câu và các quy tắc đi kèm.
00Câu hỏi
- Mỗi mẩu thông tin (repo, file ngoài repo, cấu hình agent, cấu hình hệ thống) dùng cho phạm vi nào?
- Có lên git không, lên repo nào (kit, hub, repo nền tảng, không git, vault)?
- Mất máy thì dựng lại từ đâu?
Trả lời ngắn: phân theo 13 phạm vi, mỗi phạm vi đúng một nguồn chuẩn. Sinh lại được thì commit nguồn sinh, không commit bản sinh. Riêng một máy mà không sinh lại được thì vào ops/<máy>/ của hub kèm bootstrap.md. Hai thứ quan trọng nhất khi mất máy là dữ liệu chạy và khởi động khi boot, không phải file cấu hình.
01Khung phân loại
| Phạm vi | Ví dụ | Nguồn chuẩn | Git? | Dựng lại |
|---|---|---|---|---|
| Mọi dự án | luật làm việc với agent, hồ sơ, mẫu, schema, hook, hợp đồng CLI | kit | có | clone |
| Sản phẩm | luật sản phẩm, bảng repo, vai, env (không secret), flow, tài liệu vận hành, CLI dự án, trạng thái phát hành | hub | có | clone |
| Hồ sơ server | config CLI chỉ server dùng: deploy, chứng chỉ, proxy, DB | hub config/ | có; máy khác *.local.json | clone |
| Repo | code, test, testid, CLAUDE.md kỹ thuật + khối rule-block, skill của repo | repo nền tảng | có | clone + lệnh deploy |
| Cấu hình máy | CLAUDE.md bàn làm việc, map, README tầng, manifest tiến trình (tên khoá env, không giá trị), route proxy thêm tay, cron | hub ops/<máy>/ | có, không secret | bootstrap.md + lệnh check |
| Trạng thái máy | dump tiến trình, config proxy đang chạy, launcher, biến shell | sinh lại / export định kỳ | không | từ cấu hình máy + lệnh setup |
| Khởi động | unit systemd, pm2 startup, linger | lệnh ghi trong bootstrap.md | có (lệnh) | chạy lại lệnh, cần root |
| Người | memory, phiên, settings cá nhân, file cấp user (chỉ dòng import, do setup sinh) | ~/.claude | không | mất được; sự thật sản phẩm không được chỉ nằm ở đây |
| Secret thật | env có mật khẩu, token, khoá, keystore, chứng chỉ | vault/ (700, agent không đọc) | không, trừ quyết định riêng ghi ở decision/ | bản sao an toàn đã quyết + xin lại chứng chỉ |
| Secret test | tài khoản test cho máy dev | chỗ dự án đã quyết | theo quyết định | clone |
| Dữ liệu chạy | DB, file người dùng tải lên, bộ cài đã phát hành | production: backup ngoài máy, đã thử restore; máy test: được không backup nếu có quyết định ghi lại | không | restore backup; bộ cài từ release của git host |
| Quyết định | kết quả phản biện hoặc thiết kế đã chốt | hub doc/decision/YYYY-MM-DD-<chủ-đề>.md | có | clone |
| Một lần chạy | report, ảnh, log, tóm tắt phiên | work/run/<ngày>/<tác-vụ>/ | không | không cần |
02Cây quyết định
Gặp một mẩu thông tin mới: trả lời lần lượt, dừng ở câu “có” đầu tiên.
- Là mật khẩu, token, khoá, chứng chỉ? → secret thật:
vault/. - Là dữ liệu người dùng, DB, file đã phát hành? → dữ liệu chạy: không git; production backup ngoài máy.
- Sinh lại được bằng lệnh từ thứ khác đã có? → không commit bản sinh, commit nguồn sinh và lệnh.
- Đúng cho mọi dự án của công ty? → kit.
- Đúng cho cả sản phẩm, mọi máy? → hub.
- Chỉ một repo cần? → repo nền tảng.
- Chỉ máy này cần, không sinh lại được? → hub
ops/<máy>/+bootstrap.md. - Chỉ một người hoặc một lần chạy? →
~/.claudehoặcwork/run/. Nếu là sự thật về sản phẩm thì quay lại câu 5.
03Quy tắc
- Một nguồn, chỗ khác chỉ trỏ. Trùng có chủ đích (khối rule-block ở mỗi repo nền tảng) phải có lệnh kiểm lệch.
- Sinh lại được thì commit nguồn sinh: manifest tiến trình chỉ ghi tên khoá env; route do dịch vụ tự đẩy thì không chép.
- Không commit secret ngoài chỗ dự án đã quyết rõ; lệnh export chặn nội dung có dấu hiệu secret; chạy secret-scan trước commit.
- Mọi thứ một máy đi kèm
bootstrap.mdvà lệnh check so máy với hồ sơ. - Sự thật sản phẩm không chỉ nằm ở memory hay settings của một người; memory chỉ trỏ tới doc.
- Thư mục công khai không chứa file ẩn, sao lưu, secret. Sao lưu của agent ở
work/run/<ngày>/;vault/chặn agent bằng luật deny, chỉ người và lệnh của dự án ghivault/backup/. - Luật phải tới mọi phiên: import ở file cấp user, không ở CLAUDE.md thư mục cha.
- Tên máy theo vai trò (
ops/<sp>-test/), không theo IP.
04Phản ví dụ đã gặp
| Sai | Hậu quả | Sửa |
|---|---|---|
| Bảng repo, viết tắt, cảnh báo ở file ngoài git, lệch thực tế | mất máy là mất; agent đọc thông tin cũ | hub doc/repos.md + doc/rule.md; file cũ chỉ trỏ |
| Một skill ba bản lệch nhau ở ba chỗ | không biết bản nào đúng | một nguồn ở repo công cụ, cài bằng lệnh |
| File sao lưu trong thư mục web công khai | ai cũng tải được bản cũ | sao lưu ra work/run/<ngày>/ |
| Memory chứa sự thật sản phẩm (keystore, quy tắc phát hành, server) | người khác, máy khác không thấy | hub doc/release/, doc/server/; memory chỉ trỏ |
| Luật sản phẩm import từ CLAUDE.md thư mục cha | phiên mở trong repo bỏ qua | import ở file cấp user, do lệnh setup sinh |
| Khoá ký (APNs) nằm trong git repo app, app không dùng | lộ khoá cho mọi người có repo | gỡ khỏi git, thư mục secret vào gitignore, tài liệu dựng lại và thay khoá ở hub; lịch sử cũ còn khoá thì thay và revoke |
| Không backup dữ liệu chạy mà không ai quyết | mất máy = mất dữ liệu | máy test: ghi quyết định “không backup” + cách dựng dữ liệu test; production: bắt buộc backup ngoài máy |
| Không tự khởi động khi boot | reboot = dịch vụ tắt | ghi việc chờ trong bootstrap.md, cần người có quyền root |
| Script vận hành nằm trong thư mục bản chạy, ngoài git, đường dẫn tương đối | gãy khi đổi cây; không ai thấy | vào hub, đường dẫn qua env |
| Cron gọi một file không tồn tại, hồ sơ máy export đúng dòng sai | hồ sơ “khớp” với cấu hình hỏng | lệnh check phải thử chạy, không chỉ so chuỗi |
05Hồ sơ máy và dựng lại
ops/<máy>/ trong hub giữ thứ không sinh lại được của một máy, không secret: CLAUDE.md bàn làm việc, map.md, README tầng, settings agent mẫu, manifest tiến trình, route proxy thêm tay, crontab. Hai lệnh đi kèm: export (chụp từ máy đang chạy, mặc định xem trước) và check (so máy với hồ sơ). bootstrap.md ghi thứ tự dựng lại và việc còn chờ người có quyền:
- user và công cụ (runtime, SDK)
- clone repo: hub, kit, repo nền tảng (sửa), bản chạy (clone riêng)
- thư mục cha bảy tầng,
vault/700, symlink - vault: env, chứng chỉ, khoá (từ bản sao an toàn đã quyết)
- dữ liệu: restore backup, hoặc tạo dữ liệu test mới
- dịch vụ theo manifest, lưu danh sách tiến trình
- proxy, route thêm tay
- cron
- kiểm: lệnh status, lệnh check, lệnh kiểm của kit
06Ví dụ MiniGate
Luật làm việc với agent ở kit (~/kit/agent-kit, pin trong kit.lock). Luật sản phẩm, bảng repo, tài liệu vận hành, quyết định ở hub product/minigate-hub/docs/; luật nạp qua file cấp user do mgctl setup sinh. Hồ sơ máy ở hub ops/minigate-test/ với mgctl server export | check. Secret thật ở ~/vault/config, bản sao trong hub secrets/ theo quyết định riêng của dự án (repo private, agent bị luật deny chặn). Dữ liệu chạy không backup vì là máy test, có quyết định ghi lại; mất máy dựng lại từ git, bootstrap.md và dữ liệu test mới.
Bộ ghi chú này là thông tin “mọi dự án” nên nằm trong kit (doc/method/) và được máy test phục vụ công khai qua một route tĩnh; không nằm ở bàn làm việc của máy.
Trước khi hỏi “file này để đâu”, hỏi “mất máy thì cái gì không lấy lại được”. Đó mới là thứ cần một chỗ chắc chắn.