Hướng dẫn sử dụng Latent Chain Mode trong Claude Code Guardian
Version 1.3.0 | Updated: December 12, 2025
- Tổng quan
- 3 Flow Commands
- Flow chuẩn 5 bước
- Diff-Based Editing (NEW!)
- Output Format với Phase Icons
- Auto-Attach Feature
- Ví dụ thực tế
- Prompt Pattern cho Claude
- Tips & Best Practices
Latent Chain Mode là phương pháp làm việc mô phỏng hidden-state reasoning (suy luận ẩn), lấy cảm hứng từ các paper nghiên cứu của Stanford/Princeton/UIUC.
| Benefit | Mô tả |
|---|---|
| 70-80% Token Reduction | Chỉ gửi delta (thay đổi), không full context |
| 3-4x Speed | Nhanh hơn cho multi-agent workflows |
| Structured Thinking | 4 phase rõ ràng: analysis → plan → impl → review |
| Traceable Decisions | Mọi decision được track với ID |
- Task có 2+ bước trở lên
- Bug fix phức tạp
- Feature mới cần thiết kế
- Refactoring lớn
- Code review có nhiều file
NEW in v1.2.2 - Quick commands cho các use cases phổ biến
| Flow | Command | Use Case | Phases |
|---|---|---|---|
| A | /latent-fix |
Quick fix 1-2 patches, file đang mở | analysis → plan → impl → review |
| B | /latent-feature |
Feature/Refactor nhiều files | deep analysis → detailed plan → iterative impl → review |
| C | /latent-review |
Review/Audit code (không sửa) | analysis → plan → structured output |
Dùng khi: Bug đơn giản, chỉ 1-2 files cần sửa
/latent-fix # Fix file đang mở
/latent-fix src/auth/login.ts # Fix file cụ thểQuy trình tự động:
- 🔍 Analysis: Xác định vấn đề
- 📋 Plan: Liệt kê 1-2 patches
- 🔧 Impl: Apply patches
- ✅ Review: Verify & complete
Dùng khi: Feature mới hoặc refactoring lớn
/latent-feature "Add dark mode toggle"
/latent-feature "Refactor auth" --constraints "No breaking changes"Quy trình tự động:
- 🔍 Deep Analysis: Nghiên cứu codebase
- 📋 Detailed Plan: Sub-tasks với dependencies
- 🔧 Iterative Impl: Apply patches theo thứ tự
- ✅ Comprehensive Review: Tests + validation
Dùng khi: Review/Audit code mà không sửa
/latent-review # Review file đang mở
/latent-review src/auth/ # Review folder
/latent-review src/api/users.ts # Review file cụ thểOutput structured:
- Hot spots identified
- Risks & issues
- Recommendations (không tự động sửa)
Quick check trạng thái latent context hiện tại:
/latent-status # Show current context
/latent-status fix-auth-bug # Show specific contextNEW in v1.2.2 - Standardized output với phase icons
| Phase | Icon | Ý nghĩa |
|---|---|---|
| analysis | 🔍 | Đang phân tích vấn đề |
| plan | 📋 | Đang lên kế hoạch |
| impl | 🔧 | Đang thực hiện |
| review | ✅ | Kiểm tra hoàn thành |
🔍 [analysis] <tiêu đề ngắn>
<1-2 câu mô tả>
[Hot Spots] file:line, file:line
[Decisions] D001: ..., D002: ...
[Risks] nếu có
---
📋 [plan] <số patches/tasks>
[Patches] hoặc [Sub-tasks]
1. file:line - mô tả
2. file:line - mô tả
---
🔧 [impl] Patch N/M: <name>
Applied: <count> | Tests: <status>
---
✅ [review] Complete
Files: N | Patches: M | Tests: passed
🔍 [analysis] Token expiry bug in auth module
Token không được refresh, gây logout sau 1h.
[Hot Spots] src/auth/token.ts:45-60
[Decisions] D001: Add token refresh mechanism
[Risks] Active sessions may be affected
---
📋 [plan] 2 patches
[Patches]
1. src/auth/token.ts:45 - Add refresh logic
2. src/config/auth.ts:12 - Configurable expiry
---
🔧 [impl] Patch 1/2: token.ts
Applied: 1 | Tests: pending
🔧 [impl] Patch 2/2: auth.ts
Applied: 2 | Tests: running...
---
✅ [review] Complete
Files: 2 | Patches: 2 | Tests: 47 passed
NEW in v1.2.2 - Tự động attach latent context
CCG tự động tạo và attach latent context khi:
- Có workflow task đang chạy (
workflow_task_start) - Claude gọi một trong các tools:
guard_validatetesting_run- Write operations (Edit, Write)
- Chưa có latent context cho task đó
{
"modules": {
"latent": {
"enabled": true,
"autoAttach": true // Enable auto-attach (default: true)
}
}
}Nếu muốn control manual:
{
"modules": {
"latent": {
"autoAttach": false
}
}
}Xem: src/hooks/pre-tool-call.hook.ts (line 330-420)
- Restart MCP server để load Latent Module
- Kiểm tra config trong
.ccg/config.json:
{
"modules": {
"latent": {
"enabled": true,
"maxContexts": 50,
"autoMerge": true,
"persist": true,
"persistPath": ".ccg/latent-contexts.json"
}
}
}Khi bắt đầu việc lớn, tạo context:
{
"tool": "latent_context_create",
"args": {
"taskId": "fix-auth-refresh",
"phase": "analysis",
"constraints": [
"Không breaking change",
"Phải pass toàn bộ test hiện tại"
],
"files": ["src/auth/login.ts"]
}
}Output:
- Tạo
AgentLatentContextmới - Lưu vào
.ccg/latent-contexts.json - Version = 1
Thay vì viết essay dài, Claude trả về JSON ngắn gọn:
{
"summary": "Xác định root cause ở login.ts:45-60, thiếu logic refresh token.",
"contextDelta": {
"codeMap": {
"hotSpots": ["src/auth/login.ts:45-60"]
},
"decisions": [
{
"id": "D001",
"summary": "Root cause: không refresh token",
"rationale": "Token hết hạn sau 1h, không có cơ chế refresh."
}
],
"risks": ["Có thể ảnh hưởng session hiện tại"]
},
"actions": []
}Sau đó gọi tool để merge:
{
"tool": "latent_context_update",
"args": {
"taskId": "fix-auth-refresh",
"delta": {
"codeMap": { "hotSpots": ["src/auth/login.ts:45-60"] },
"decisions": [{ "id": "D001", "summary": "...", "rationale": "..." }],
"risks": ["Có thể ảnh hưởng session hiện tại"]
}
}
}Khi hoàn thành 1 phase:
{
"tool": "latent_phase_transition",
"args": {
"taskId": "fix-auth-refresh",
"toPhase": "plan",
"summary": "Hoàn tất phân tích, đã xác định nguyên nhân và phạm vi ảnh hưởng."
}
}Flow chuẩn:
┌─────────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ ANALYSIS │ ──► │ PLAN │ ──► │ IMPL │ ──► │ REVIEW │
│ │ │ │ │ │ │ │
│ - Đọc yêu │ │ - Tasks │ │ - Patch │ │ - Check │
│ cầu │ │ - Thứ │ │ - Code │ │ - Test │
│ - Hot spots │ │ tự │ │ │ │ - Done? │
│ - Decisions │ │ - Deps │ │ │ │ │
└─────────────┘ └─────────┘ └─────────┘ └─────────┘
│ │ │
└──────────────────┴───────────────┘
(có thể quay lại nếu cần)
Valid transitions:
- analysis → plan, impl
- plan → impl, review
- impl → review, plan (quay lại nếu phát hiện vấn đề)
- review → impl, analysis (quay lại nếu cần fix)
Trong phase impl, dùng patch thay vì paste code:
{
"tool": "latent_apply_patch",
"args": {
"taskId": "fix-auth-refresh",
"target": "src/auth/login.ts",
"patch": "--- a/src/auth/login.ts\n+++ b/src/auth/login.ts\n@@ -45,3 +45,5 @@\n-const token = generateToken();\n+const token = generateToken();\n+scheduleTokenRefresh(token, 50 * 60 * 1000);\n"
}
}v1.3.0 - Advanced patch application system
| Traditional | Diff-Based |
|---|---|
| Paste full file content | Chỉ gửi thay đổi (diff) |
| ~500-2000 tokens/file | ~50-200 tokens/patch |
| Dễ conflict | Auto-merge thông minh |
| Phải đọc lại cả file | Chỉ focus vào phần sửa |
CCG sử dụng unified diff format chuẩn:
--- a/src/auth/token.ts
+++ b/src/auth/token.ts
@@ -45,3 +45,5 @@
const token = generateToken();
-// TODO: Add refresh logic
+scheduleTokenRefresh(token, 50 * 60 * 1000);
+logger.info('Token refresh scheduled');Giải thích:
---/+++: File gốc vs file mới@@: Vị trí thay đổi (line 45, 3 dòng context)-: Dòng bị xóa+: Dòng được thêm
CCG tự động xử lý patches:
- Thử git apply trước (nếu có git)
- Fallback manual patch nếu không có git
- Tạo file mới nếu patch tạo file
// Internal API
const applicator = new PatchApplicator(projectRoot, logger);
const result = await applicator.applyPatch({
target: 'src/auth/token.ts',
patch: unifiedDiff,
dryRun: false // Set true để preview
});Kiểm tra patch trước khi apply:
{
"tool": "latent_apply_patch",
"args": {
"taskId": "fix-auth",
"target": "src/auth/token.ts",
"patch": "...",
"dryRun": true
}
}Context được merge thông minh, không replace:
// Update 1
{ "delta": { "risks": ["Risk A"] } }
// Update 2
{ "delta": { "risks": ["Risk B"] } }
// Kết quả: risks = ["Risk A", "Risk B"]
// Không phải: risks = ["Risk B"]Merge rules:
- Arrays: Append + deduplicate
- Objects: Deep merge
- Primitives: Replace
- Giữ patch nhỏ - 1 patch = 1 thay đổi logic
- Thêm context - Ít nhất 3 dòng context trước/sau
- Test dryRun - Luôn preview trước patch phức tạp
- Track artifacts - Update context sau mỗi patch
// Sau khi apply patch
{
"tool": "latent_context_update",
"args": {
"taskId": "fix-auth",
"delta": {
"artifacts": {
"patches": ["src/auth/token.ts"]
}
}
}
}Sau đó update artifacts:
{
"tool": "latent_context_update",
"args": {
"taskId": "fix-auth-refresh",
"delta": {
"artifacts": {
"patches": ["src/auth/login.ts"]
}
}
}
}Khi mọi thứ OK:
{
"tool": "latent_complete_task",
"args": {
"taskId": "fix-auth-refresh",
"summary": "Đã fix bug refresh token, tests passed."
}
}Yêu cầu: "User bị logout sau 1h dù không inactive"
// latent_context_create
{
"taskId": "fix-session-timeout",
"phase": "analysis",
"constraints": ["Không breaking change", "Pass all tests"],
"files": ["src/auth/session.ts", "src/auth/token.ts"]
}
// latent_context_update (sau khi phân tích)
{
"delta": {
"codeMap": {
"hotSpots": ["src/auth/token.ts:78-92"],
"components": ["AuthService", "TokenManager"]
},
"decisions": [{
"id": "D001",
"summary": "Token expiry hardcoded 1h, không refresh",
"rationale": "Tìm thấy `expiresIn: 3600` ở line 82"
}],
"risks": ["Active sessions có thể bị ảnh hưởng"]
}
}// latent_phase_transition
{ "toPhase": "plan", "summary": "Đã xác định root cause" }
// latent_context_update
{
"delta": {
"decisions": [{
"id": "D002",
"summary": "Thêm refresh token mechanism",
"rationale": "Refresh 5 phút trước khi hết hạn"
}, {
"id": "D003",
"summary": "Update config cho expiry time",
"rationale": "Cho phép customize qua env"
}]
}
}// latent_phase_transition
{ "toPhase": "impl" }
// latent_apply_patch (patch 1)
{
"target": "src/auth/token.ts",
"patch": "..." // unified diff
}
// latent_apply_patch (patch 2)
{
"target": "src/config/auth.config.ts",
"patch": "..." // unified diff
}
// latent_context_update
{
"delta": {
"artifacts": {
"patches": ["src/auth/token.ts", "src/config/auth.config.ts"]
}
}
}// latent_phase_transition
{ "toPhase": "review", "summary": "Đã apply 2 patches" }
// Kiểm tra constraints
// - "Không breaking change" ✓
// - "Pass all tests" ✓
// latent_complete_task
{
"taskId": "fix-session-timeout",
"summary": "Fixed session timeout: added token refresh mechanism + configurable expiry"
}## Latent Chain Mode
Khi làm việc với CCG, ưu tiên **Latent Chain Mode** cho các task từ 2 bước trở lên.
### Quy tắc bắt buộc:
1. **Bắt đầu task** → Gọi `latent_context_create`
2. **Output format** → Dùng LatentResponse (summary + contextDelta + actions)
3. **Update context** → Gọi `latent_context_update` với delta, KHÔNG lặp full context
4. **Sửa code** → Dùng `latent_apply_patch`, không paste code trực tiếp
5. **Chuyển phase** → Dùng `latent_phase_transition` khi hoàn thành 1 phase
6. **Kết thúc** → Gọi `latent_complete_task`
### Quy tắc văn bản:
- Summary tối đa **2 câu** (200 chars)
- KHÔNG viết essay giải thích
- KHÔNG lặp thông tin đã có trong context
- Mọi decision phải có ID (D001, D002...)
### 4 Phases:
| Phase | Mục tiêu | Output |
|-------|----------|--------|
| analysis | Hiểu vấn đề | hotSpots, risks, decisions |
| plan | Lên kế hoạch | tasks list, dependencies |
| impl | Thực hiện | patches, code changes |
| review | Kiểm tra | verify constraints, tests |Khi user nói /latent-start <task>, Claude nên:
- Gọi
latent_context_create - Chạy analysis phase
- Output kế hoạch ngắn gọn
- Keep summary short - 1-2 câu max
- Use decision IDs - D001, D002... để track
- Send delta only - Không full context
- Transition explicitly - Dùng tool để chuyển phase
- Track patches - Ghi lại trong artifacts
- Viết giải thích dài
- Lặp thông tin từ context
- Gửi full context mỗi lần update
- Skip phase transition
- Paste code thay vì apply patch
// Xem context hiện tại
{ "tool": "latent_context_get", "args": { "taskId": "xxx" } }
// Xem với history
{ "tool": "latent_context_get", "args": { "taskId": "xxx", "includeHistory": true } }
// List tất cả contexts
{ "tool": "latent_list_contexts" }
// Module status
{ "tool": "latent_status" }
// Xóa context cũ
{ "tool": "latent_delete_context", "args": { "taskId": "xxx" } }Khi token gần threshold (70-85%):
- Chỉ gửi
contextDeltatối thiểu - Không include actions
- Ưu tiên complete task nhanh
Latent Chain Mode integrates with CCG's completion gates and checkpoints:
- Checkpoints: Auto-created before risky impl phase changes. Use
resource_checkpoint_diffto compare. - Completion Gates: The
implandreviewphases may require test/guard evidence before completion. - nextToolCalls: If gates block completion, check
nextToolCallsfor suggested actions.
See Auto-Checkpoints Guide and Completion Gates Guide for details.
- PROJECT_DOCUMENTATION.md - Full module docs
- USER_GUIDE.md - User guide với tools reference
- paper.md - Latent Chain Mode specification
- improve_UX.md - UX analysis và proposals
- src/modules/latent/ - Source code
- templates/commands/ - Slash command templates
| File | Command |
|---|---|
latent-fix.md |
/latent-fix - Quick fix |
latent-feature.md |
/latent-feature - Feature/Refactor |
latent-review.md |
/latent-review - Code review |
latent-status.md |
/latent-status - Status check |
ccg-latent.md |
/ccg latent - Full latent commands |
- NEW: Diff-Based Editing with
PatchApplicator - NEW:
DeltaMergerfor intelligent context merging - NEW: Unified diff format support
- NEW: Dry run mode for patch preview
- Updated: Best practices for diff-based workflows
- Updated: Examples with unified diff format
- NEW: 3 Flow Commands (
/latent-fix,/latent-feature,/latent-review) - NEW:
/latent-statusquick status check - NEW: Auto-Attach feature in pre-tool-call hook
- NEW: Standardized output format with phase icons
- Updated: TOC với các sections mới
- Updated: Examples với real output format
- Initial release
Claude Code Guardian - Latent Chain Mode v1.3.0