Best Practices Claude Code: CLAUDE.md vs settings.json, Research-Plan-Execute Workflow Và "Challenge Claude" Patterns

Tại Sao Developer Giỏi Vẫn Bị Claude Ignore Instructions?

Một trong những thắc mắc phổ biến nhất trên Reddit về Claude Code:

"Tôi đã viết 'NEVER do X' bằng chữ hoa trong CLAUDE.md. Tại sao Claude vẫn làm X?"

Câu trả lời từ shanraisshan's best practices repo — một trong những repos được reference nhiều nhất trong community:

"Don't put 'NEVER add Co-Authored-By' in CLAUDE.md when attribution.commit is deterministic."

Nói cách khác: có những thứ thuộc về CLAUDE.md, và có những thứ thuộc về settings.json. Hiểu sự khác biệt này là foundation của mọi best practice khác.

CLAUDE.md vs settings.json: Hai Tầng Với Vai Trò Khác Nhau Hoàn Toàn

CLAUDE.md: Memory và Context

CLAUDE.md là working knowledge base của project. Nó lưu:

• Project context: Tech stack, cấu trúc folder, naming conventions
• Soft guidelines: Code style preferences, preferred patterns
• File imports: Dùng @path/to/file để pull content từ files khác vào context
• Workflow documentation: Cách thức làm việc trong project cụ thể này

CLAUDE.md được version control — nó thay đổi theo project, theo team conventions, theo thời gian. Đây là nơi bạn giải thích tại sao và cách làm.

settings.json: Operational Governance

settings.json quản lý behavior deterministic — những thứ phải xảy ra 100% thời gian:

• Permissions: Tool nào được phép chạy, file nào được đọc/ghi
• Model selection: Dùng model nào cho loại task nào
• Output styles: Format của responses
• Sandboxing: Isolation level cho autonomous operations
• Keybindings: Custom shortcuts
• Attribution: Co-author format cho commits

Nếu muốn Claude không bao giờ commit files .env → settings.json với permission deny rule, không phải CLAUDE.md với "NEVER commit .env".

Rule of thumb: Memory trong CLAUDE.md. Governance trong settings.json.

Architecture Pattern: Research → Plan → Execute → Review → Ship

Community consensus mạnh nhất về workflow — được gọi là "5-phase gate methodology":

Phase 1: Research

Trước khi làm bất cứ gì, Claude cần explore và understand:

• Đọc relevant code files
• Tìm dependencies và side effects
• Hiểu existing patterns trong codebase

Prompt: "Before writing any code, explore the codebase and tell me what you find about [area]. List all files touched by this change."

Phase 2: Plan

Plan phải được approve trước khi bất kỳ code nào được viết. Key insight từ repo:

"Start with a minimal spec or prompt and ask Claude to interview you using AskUserQuestion tool, then make a new session to execute the spec."

Spin up second Claude instance (fresh context) để review plan như staff engineer. Fresh perspective bắt được assumptions mà original context bỏ qua.

Phase 3: Execute

Implementation với boundaries rõ ràng. State desired outcomes, không phải implementation steps cụ thể. Claude tự quyết định how — bạn quyết định what và why.

Phase 4: Review

Multi-layer review:

• Automated: tests, type checks, linting
• AI: "Prove to me this works" → Claude diff giữa main và branch
• Human: business logic, edge cases, security implications

Phase 5: Ship

Deploy với confidence vì mọi layer đã được kiểm tra.

"Challenge Claude" Patterns: 3 Prompts Tạo Accountability

Đây là section được cite nhiều nhất từ repo của shanraisshan:

Pattern 1: "Grill Me"

"Grill me on these changes and don't make a PR until I pass your test."

Đảo ngược vai trò: Claude là examiner, bạn là người cần chứng minh implementation đúng. Buộc bạn hiểu code của mình, không chỉ accept output của AI.

Pattern 2: "Prove To Me This Works"

"Prove to me this works."

Claude diff giữa main branch và current branch, list tất cả changes, explain tại sao mỗi change là đúng. Không chấp nhận "trust me" từ AI.

Pattern 3: "Scrap And Start Over"

"Knowing everything you know now, scrap this and implement the elegant solution."

Pattern mạnh nhất trong ba cái. Sau khi có working solution (kể cả solution xấu), buộc Claude rethink từ đầu với full context. Kết quả thường là solution đẹp hơn nhiều — vì AI bây giờ hiểu toàn bộ problem space.

Code Search: Grep + Glob Beats RAG Cho Codebase

Insight kỹ thuật quan trọng từ repo, supported bởi Anthropic engineering decision:

Claude Code đã thử và loại bỏ vector databases (RAG) cho code search. Lý do:

• Code drift out of sync với embeddings → search returns stale results
• Permission management phức tạp
• Overhead không đáng khi grep + glob đơn giản hơn và chính xác hơn

Grep + glob tìm kiếm trực tiếp trong file system → luôn up-to-date, không cần index maintenance.

Áp dụng: Đừng over-engineer code search setup. Grep works. Stay simple.

Skill Description: Viết Cho Model, Không Phải Cho Human

Khi viết Skills, phần description phải trả lời câu hỏi của model: "When should I fire this skill?"

Common mistakes:

Mistake	Better
"Skill này xử lý emails"	"Load khi user cần soạn, phân loại, hoặc tóm tắt emails. Áp dụng corporate tone guidelines."
"A skill for data analysis"	"Activate when performing quantitative analysis on structured data. Includes pandas patterns, visualization defaults, and statistical test recommendations."
Liệt kê tính năng	Mô tả trigger conditions

Nguyên tắc: Don't state the obvious. Focus vào gì pushes Claude ra khỏi default behavior.

Three-Layer Architecture: Subagents, Commands, Skills

Repo mô tả ba tầng distinct:

Subagents (.claude/agents/)

Autonomous actors trong isolated contexts. Có custom tools, permissions, persistent identity. Phù hợp cho long-running tasks cần scope của riêng chúng.

Commands (.claude/commands/)

Knowledge injected vào existing context. Workflow orchestration. Không isolate — chia sẻ context với main session.

Skills (.claude/skills/)

Configurable, preloadable knowledge. Progressive disclosure — load khi cần, không load khi không cần. Shareable across sessions và users.

Three layers phục vụ ba nhu cầu khác nhau. Sai tầng → wrong results.

Hot Features Từ Community (Beta/Recent)

• Auto Mode: Background safety classifier tự handle permission prompts — không cần approve từng action nhỏ
• Scheduled Tasks (/schedule): Cloud-based recurring prompts, chạy kể cả khi máy tính tắt
• Code Review: Multi-agent PR analysis catching bugs và vulnerabilities
• Channels: Push events từ Telegram/Discord vào running sessions

Tóm Tắt Checklist

Best practices core cho mọi Claude Code project:

1. CLAUDE.md: context và memory. settings.json: permissions và behavior deterministic
2. Luôn Research → Plan → Execute → Review → Ship, không skip phases
3. Dùng "Challenge Claude" patterns để tạo accountability
4. Grep + glob cho code search, không cần RAG
5. Skill descriptions viết cho model's decision-making, không phải human readability
6. Chọn đúng tầng: Subagent cho isolation, Command cho orchestration, Skill cho reusable knowledge

Muốn explore thêm? Xem Claude Code documentation và Claude Cowork cho non-technical workflows.

---

Nguồn Tham Khảo

Bài viết dựa trên: claude-code-best-practice repository bởi shanraisshan, đăng trên GitHub. Link gốc: github.com/shanraisshan