{"product_id":"claude-md-masterclass-tối-ưu-workspace-cho-claude-code","title":"CLAUDE.md Masterclass — Tối ưu workspace cho Claude Code","description":"\n\u003ch2\u003eCLAUDE.md là gì và tại sao nó quan trọng?\u003c\/h2\u003e\n\u003cp\u003eCLAUDE.md là file Markdown đặc biệt mà Claude Code đọc ngay khi khởi động. Nội dung của file này trở thành \u003cstrong\u003esystem context\u003c\/strong\u003e cho toàn bộ session — mọi quyết định Claude đưa ra đều được định hình bởi những gì bạn viết trong CLAUDE.md.\u003c\/p\u003e\n\n\u003cp\u003eHãy nghĩ CLAUDE.md như là bản onboarding document cho developer mới gia nhập team — ngoại trừ \"developer mới\" ở đây là một AI agent với khả năng đọc và ghi code. Càng viết rõ ràng, Claude càng làm việc hiệu quả hơn, ít sai hơn, và ít cần correction hơn.\u003c\/p\u003e\n\n\u003cblockquote\u003e\n  \u003cp\u003eMột CLAUDE.md tốt có thể tiết kiệm 30-50% tokens trong một session dài, vì Claude không phải \"hỏi\" hay \"đoán\" những thông tin cơ bản về project.\u003c\/p\u003e\n\u003c\/blockquote\u003e\n\n\u003ch3\u003eSự khác biệt giữa project với và không có CLAUDE.md\u003c\/h3\u003e\n\u003cp\u003e\u003cstrong\u003eKhông có CLAUDE.md:\u003c\/strong\u003e\u003c\/p\u003e\n\u003cul\u003e\n  \u003cli\u003eClaude phải khám phá codebase từ đầu mỗi session\u003c\/li\u003e\n  \u003cli\u003eCó thể đưa ra suggestions không phù hợp với conventions\u003c\/li\u003e\n  \u003cli\u003eTốn nhiều tokens cho context building\u003c\/li\u003e\n  \u003cli\u003eKết quả inconsistent giữa các session\u003c\/li\u003e\n\u003c\/ul\u003e\n\n\u003cp\u003e\u003cstrong\u003eCó CLAUDE.md tốt:\u003c\/strong\u003e\u003c\/p\u003e\n\u003cul\u003e\n  \u003cli\u003eClaude hiểu ngay context và constraints\u003c\/li\u003e\n  \u003cli\u003eSuggestions phù hợp với team conventions ngay từ đầu\u003c\/li\u003e\n  \u003cli\u003eTiết kiệm tokens, session nhanh hơn\u003c\/li\u003e\n  \u003cli\u003eKết quả consistent và predictable\u003c\/li\u003e\n\u003c\/ul\u003e\n\n\u003ch2\u003eFile Hierarchy\u003c\/h2\u003e\n\u003cp\u003eClaude Code đọc CLAUDE.md từ nhiều vị trí theo thứ tự ưu tiên:\u003c\/p\u003e\n\n\u003ch3\u003e1. Project root: \u003ccode\u003e\/project\/CLAUDE.md\u003c\/code\u003e\n\u003c\/h3\u003e\n\u003cp\u003eFile chính, chứa project-specific context. Nên được commit vào version control để toàn team benefit.\u003c\/p\u003e\n\n\u003ch3\u003e2. Global: \u003ccode\u003e~\/.claude\/CLAUDE.md\u003c\/code\u003e\n\u003c\/h3\u003e\n\u003cp\u003ePersonal preferences áp dụng cho mọi project. Ví dụ: coding style cá nhân, preferred tools, shortcuts.\u003c\/p\u003e\n\n\u003cpre\u003e\u003ccode\u003e# ~\/.claude\/CLAUDE.md (personal global config)\n\n## My Preferences\n- Always use TypeScript, never plain JavaScript\n- Prefer functional programming patterns\n- Use descriptive variable names, avoid abbreviations\n- Always add JSDoc for public functions\n\n## My Common Tools\n- Package manager: pnpm (not npm or yarn)\n- Test framework: Vitest\n- Linter: ESLint + Prettier\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003ch3\u003e3. Subdirectory: \u003ccode\u003e\/project\/.claude\/CLAUDE.md\u003c\/code\u003e\n\u003c\/h3\u003e\n\u003cp\u003eContext cho một phần cụ thể của project. Hữu ích cho monorepos.\u003c\/p\u003e\n\n\u003cpre\u003e\u003ccode\u003e\/project\/\n├── CLAUDE.md              # Root project context\n├── .claude\/\n│   ├── CLAUDE.md          # Advanced overrides\n│   ├── settings.json      # Tool permissions\n│   └── hooks\/             # Automation hooks\n├── packages\/\n│   ├── frontend\/\n│   │   └── CLAUDE.md      # Frontend-specific context\n│   └── backend\/\n│       └── CLAUDE.md      # Backend-specific context\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003cp\u003eClaude merge tất cả các file CLAUDE.md theo thứ tự ưu tiên, với subdirectory CLAUDE.md override parent khi có conflict.\u003c\/p\u003e\n\n\u003ch2\u003eCấu trúc CLAUDE.md chuẩn\u003c\/h2\u003e\n\u003cp\u003eSau đây là template structure được khuyến nghị:\u003c\/p\u003e\n\n\u003cpre\u003e\u003ccode\u003e# CLAUDE.md\n\n## Role\n[Mô tả Claude nên đóng vai trò gì trong project này]\n\n## Project Overview\n[Project này làm gì, cho ai, tại sao nó tồn tại]\n\n## Tech Stack\n[Liệt kê tất cả technologies, versions quan trọng]\n\n## Project Structure\n[Giải thích cấu trúc thư mục quan trọng]\n\n## Development Commands\n[Các lệnh thường dùng nhất]\n\n## Coding Conventions\n[Rules về code style, patterns, naming]\n\n## Architecture Decisions\n[Các quyết định kiến trúc quan trọng và lý do]\n\n## Do NOT\n[Những điều tuyệt đối không được làm]\n\n## Workflows\n[Các workflow cụ thể của team]\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003ch2\u003eCác Section cần thiết\u003c\/h2\u003e\n\n\u003ch3\u003eRole Section\u003c\/h3\u003e\n\u003cp\u003eĐây là section nhiều người bỏ qua nhưng lại rất có impact. Cho Claude biết nó đang đóng vai trò gì:\u003c\/p\u003e\n\n\u003cpre\u003e\u003ccode\u003e## Role\nBạn là senior backend engineer trong team này. Ưu tiên:\n1. Code correctness và reliability hơn tốc độ viết\n2. Security — luôn validate input, sanitize output\n3. Performance — cân nhắc database indexes và query optimization\n4. Maintainability — code phải dễ đọc và dễ test\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003ch3\u003eTech Stack Section\u003c\/h3\u003e\n\u003cp\u003eLiệt kê cụ thể, bao gồm versions quan trọng:\u003c\/p\u003e\n\n\u003cpre\u003e\u003ccode\u003e## Tech Stack\n- Runtime: Node.js 20 LTS\n- Framework: Fastify 4 (NOT Express)\n- Database: PostgreSQL 15 + Prisma 5 ORM\n- Cache: Redis 7\n- Testing: Vitest + Supertest\n- Language: TypeScript 5.3 (strict: true)\n- Deployment: Docker + Kubernetes on GCP\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003cp\u003eLưu ý: ghi rõ \"NOT Express\" nếu bạn dùng Fastify. Sự phân biệt tường minh giúp Claude không nhầm lẫn framework.\u003c\/p\u003e\n\n\u003ch3\u003eProject Structure Section\u003c\/h3\u003e\n\u003cpre\u003e\u003ccode\u003e## Project Structure\nsrc\/\n├── api\/         # Route handlers only, NO business logic\n├── services\/    # Business logic layer\n├── repositories\/ # Database access layer (Prisma queries)\n├── models\/      # TypeScript interfaces and types\n├── middleware\/  # Fastify middleware\n├── utils\/       # Pure utility functions\n└── config\/      # Configuration management\n\nIMPORTANT: Follow this layered architecture strictly.\nServices call Repositories. Routes call Services. Never skip layers.\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003ch3\u003eDevelopment Commands\u003c\/h3\u003e\n\u003cpre\u003e\u003ccode\u003e## Commands\n- Dev server: `npm run dev`\n- Run tests: `npm test`\n- Watch tests: `npm run test:watch`\n- Type check: `npm run typecheck`\n- Lint: `npm run lint`\n- DB migrate: `npx prisma migrate dev --name [description]`\n- DB studio: `npx prisma studio`\n- Docker up: `docker compose up -d`\n- Generate API docs: `npm run docs:generate`\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003cp\u003eClaude Code sẽ tự động chạy các commands này khi cần verify, mà không cần bạn nhắc nhở.\u003c\/p\u003e\n\n\u003ch3\u003eCoding Conventions\u003c\/h3\u003e\n\u003cpre\u003e\u003ccode\u003e## Conventions\n\n### Naming\n- Variables\/functions: camelCase\n- Classes\/interfaces: PascalCase\n- Constants: SCREAMING_SNAKE_CASE\n- Database tables: snake_case\n- Files: kebab-case.ts\n\n### Error Handling\n- Use custom error classes extending AppError\n- Always include error code and message\n- Log errors with context before throwing\n- Never swallow errors silently\n\n### Async\n- Always use async\/await, never .then().catch()\n- Wrap top-level async in try\/catch\n- Use Promise.all() for parallel operations\n\n### Testing\n- Unit tests for all service methods\n- Integration tests for all API endpoints\n- Use factories (not fixtures) for test data\n- Mock external services, never make real API calls in tests\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003ch3\u003eDo NOT Section\u003c\/h3\u003e\n\u003cp\u003eĐây là section quan trọng nhất để prevent mistakes:\u003c\/p\u003e\n\n\u003cpre\u003e\u003ccode\u003e## Do NOT\n- NEVER use `any` type in TypeScript — use `unknown` + type guards\n- NEVER commit environment variables or secrets\n- NEVER write raw SQL queries — use Prisma\n- NEVER modify database migrations after they've been committed\n- NEVER skip input validation in API handlers\n- NEVER use synchronous file operations (fs.readFileSync) in request handlers\n- NEVER delete or modify \/prisma\/migrations\/\n- NEVER push directly to main branch\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003ch2\u003eVí dụ từ production projects\u003c\/h2\u003e\n\n\u003ch3\u003eFull-stack SaaS application\u003c\/h3\u003e\n\u003cpre\u003e\u003ccode\u003e# CLAUDE.md — TaskFlow SaaS\n\n## Overview\nB2B task management SaaS. Multi-tenant architecture.\nEach customer (Organization) has isolated data.\n\n## Critical: Multi-tenancy\nEVERY database query MUST include organizationId filter.\nThis is the most important security requirement.\n\n```typescript\n\/\/ CORRECT\nconst tasks = await prisma.task.findMany({\n  where: { organizationId: ctx.organizationId, ...filters }\n});\n\n\/\/ WRONG — data leak risk!\nconst tasks = await prisma.task.findMany({ where: filters });\n```\n\n## Stack\n- Next.js 14 (App Router) + TypeScript\n- Prisma + PostgreSQL (Supabase)\n- Stripe for billing\n- Resend for emails\n- Vercel deployment\n\n## Key Paths\n- \/app\/(dashboard)\/ — authenticated app routes\n- \/app\/(marketing)\/ — public marketing pages\n- \/app\/api\/ — API route handlers\n- \/lib\/ — shared utilities and configs\n\n## Auth\nUsing NextAuth v5. Session always includes organizationId.\nAccess via: `const session = await auth()`\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003ch3\u003eMicroservices backend\u003c\/h3\u003e\n\u003cpre\u003e\u003ccode\u003e# CLAUDE.md — Payment Service\n\n## This Service\nHandles all payment processing for the platform.\nPart of larger microservices architecture.\n\n## Boundaries — IMPORTANT\nThis service ONLY:\n- Processes payments via Stripe\n- Stores transaction records\n- Emits payment events to message queue\n\nThis service does NOT:\n- Know about users (get user data via event or API)\n- Send emails (emit event, let notification service handle)\n- Update order status (emit event, let order service handle)\n\n## Event Schema\nEvents published to RabbitMQ exchange \"payments\":\n- payment.succeeded — { transactionId, orderId, amount, currency }\n- payment.failed — { orderId, reason, retryable }\n- payment.refunded — { transactionId, refundId, amount }\n\n## Stripe Integration\nUsing Stripe SDK v14. Webhook endpoint: \/webhooks\/stripe\nSignature verification is REQUIRED for all webhooks.\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003ch2\u003eCommon Patterns\u003c\/h2\u003e\n\n\u003ch3\u003eMonorepo Pattern\u003c\/h3\u003e\n\u003cp\u003eVới monorepo sử dụng Turborepo hoặc Nx:\u003c\/p\u003e\n\n\u003cpre\u003e\u003ccode\u003e# Root CLAUDE.md\n## Monorepo Structure\nThis is a Turborepo monorepo.\n\nApps: packages\/apps\/\n- web — Next.js frontend\n- api — Fastify backend\n- admin — Admin dashboard\n\nPackages: packages\/libs\/\n- ui — Shared component library\n- types — Shared TypeScript types\n- utils — Shared utilities\n- config — Shared configs (ESLint, TypeScript)\n\n## Rules\n- Shared types go in packages\/libs\/types, NOT in individual apps\n- UI components go in packages\/libs\/ui if used by 2+ apps\n- Each app has its own CLAUDE.md with app-specific context\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003ch3\u003eFrontend-only Project\u003c\/h3\u003e\n\u003cpre\u003e\u003ccode\u003e# CLAUDE.md — Marketing Website\n\n## Project\nStatic marketing site with Next.js + Contentful CMS.\n\n## Important: Static Generation\nALL pages must use static generation (generateStaticParams).\nNO server-side rendering, NO dynamic routes without static params.\nSite deployed on Cloudflare Pages — no Node.js runtime.\n\n## Content\nBlog posts and case studies come from Contentful.\nNever hardcode content that should be in Contentful.\n\n## Performance Budget\n- Core Web Vitals: LCP \u0026lt; 2.5s, FID \u0026lt; 100ms, CLS \u0026lt; 0.1\n- Bundle size: \u0026lt; 100KB for initial JS\n- Always check bundle impact before adding new dependencies\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003ch2\u003eAdvanced: Custom Commands\u003c\/h2\u003e\n\u003cp\u003eĐịnh nghĩa custom slash commands trong \u003ccode\u003e.claude\/commands\/\u003c\/code\u003e:\u003c\/p\u003e\n\n\u003cpre\u003e\u003ccode\u003e# .claude\/commands\/deploy-staging.md\nDeploy to staging environment:\n1. Run `npm run build` and ensure it passes\n2. Run `npm test` and ensure all tests pass\n3. Run `npm run typecheck`\n4. Create a git tag with format staging-YYYY-MM-DD-HH\n5. Push tag to trigger CI\/CD pipeline\n6. Confirm deployment URL: staging.myapp.com\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003cp\u003eGọi bằng: \u003ccode\u003e\/deploy-staging\u003c\/code\u003e\u003c\/p\u003e\n\n\u003ch2\u003eAdvanced: Memory System\u003c\/h2\u003e\n\u003cp\u003eClaude Code có thể ghi nhớ thông tin quan trọng giữa các sessions qua memory files:\u003c\/p\u003e\n\n\u003cpre\u003e\u003ccode\u003e.claude\/\n├── memory\/\n│   ├── architecture-decisions.md\n│   ├── known-issues.md\n│   └── sprint-context.md\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003cp\u003eReference trong CLAUDE.md:\u003c\/p\u003e\n\n\u003cpre\u003e\u003ccode\u003e## Memory\n- Read .claude\/memory\/architecture-decisions.md for important ADRs\n- Read .claude\/memory\/known-issues.md for current known bugs\n- Update .claude\/memory\/sprint-context.md when sprint goals change\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003ch2\u003eAdvanced: Skill References\u003c\/h2\u003e\n\u003cp\u003eEncode reusable workflows như skills:\u003c\/p\u003e\n\n\u003cpre\u003e\u003ccode\u003e.claude\/skills\/\n├── create-feature.md      # Standard feature development workflow\n├── hotfix.md              # Emergency hotfix process\n└── db-migration.md        # Database migration checklist\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003cpre\u003e\u003ccode\u003e# .claude\/skills\/create-feature.md\n## New Feature Workflow\n1. Create branch: git checkout -b feature\/[name]\n2. Update\/create relevant TypeScript interfaces in \/models\/\n3. Write failing tests first (TDD)\n4. Implement feature\n5. Ensure all tests pass\n6. Run typecheck\n7. Update API documentation if new endpoints\n8. Create PR with description following template in .github\/pull_request_template.md\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003ch2\u003eAnti-patterns cần tránh\u003c\/h2\u003e\n\n\u003ch3\u003e1. CLAUDE.md quá ngắn\u003c\/h3\u003e\n\u003cp\u003eSai:\u003c\/p\u003e\n\u003cpre\u003e\u003ccode\u003e## Stack\nNext.js, TypeScript, Prisma\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003cp\u003eĐúng: Bao gồm versions, important patterns, structure, và commands đầy đủ.\u003c\/p\u003e\n\n\u003ch3\u003e2. CLAUDE.md không cập nhật\u003c\/h3\u003e\n\u003cp\u003eCLAUDE.md phải được cập nhật khi tech stack thay đổi, conventions thay đổi, hoặc có new architectural decisions. Một CLAUDE.md lỗi thời còn tệ hơn không có.\u003c\/p\u003e\n\n\u003ch3\u003e3. Viết quá chung chung\u003c\/h3\u003e\n\u003cp\u003eSai: \u003cem\u003e\"Follow best practices\"\u003c\/em\u003e\u003c\/p\u003e\n\u003cp\u003eĐúng: \u003cem\u003e\"Use Repository pattern for all database access. Never put Prisma calls directly in route handlers.\"\u003c\/em\u003e\u003c\/p\u003e\n\n\u003ch3\u003e4. Thiếu \"Do NOT\" section\u003c\/h3\u003e\n\u003cp\u003eNhững điều không được làm thường quan trọng hơn những điều nên làm. Security issues, architectural violations thường đến từ những điều không được ghi rõ là \"forbidden\".\u003c\/p\u003e\n\n\u003ch3\u003e5. Không giải thích lý do\u003c\/h3\u003e\n\u003cp\u003eClaude (và developer mới) cần hiểu tại sao, không chỉ cái gì:\u003c\/p\u003e\n\n\u003cpre\u003e\u003ccode\u003e## Why We Use X\n- Using Fastify instead of Express: 3x better performance,\n  native schema validation, TypeScript-first design\n- Using Prisma instead of raw SQL: type-safe queries,\n  auto-generated migrations, easy schema evolution\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003ch2\u003eChecklist: CLAUDE.md hoàn chỉnh\u003c\/h2\u003e\n\u003cul\u003e\n  \u003cli\u003eRole và responsibility của Claude trong project\u003c\/li\u003e\n  \u003cli\u003eProject overview (mục đích, user, tech)\u003c\/li\u003e\n  \u003cli\u003eFull tech stack với versions\u003c\/li\u003e\n  \u003cli\u003eCấu trúc thư mục với giải thích\u003c\/li\u003e\n  \u003cli\u003eTất cả development commands\u003c\/li\u003e\n  \u003cli\u003eCoding conventions (naming, patterns, style)\u003c\/li\u003e\n  \u003cli\u003eArchitecture decisions và lý do\u003c\/li\u003e\n  \u003cli\u003eSecurity requirements\u003c\/li\u003e\n  \u003cli\u003eTesting requirements\u003c\/li\u003e\n  \u003cli\u003eExplicit \"Do NOT\" list\u003c\/li\u003e\n  \u003cli\u003eTeam-specific workflows\u003c\/li\u003e\n  \u003cli\u003eLinks đến relevant docs nếu có\u003c\/li\u003e\n\u003c\/ul\u003e\n\n\u003ch2\u003eKết luận\u003c\/h2\u003e\n\u003cp\u003eCLAUDE.md không phải là boilerplate bạn copy-paste rồi để đó — đây là living document cần được maintain như code. Đầu tư 30 phút viết CLAUDE.md tốt cho project mới sẽ tiết kiệm hàng giờ frustration và corrections về sau.\u003c\/p\u003e\n\n\u003cp\u003eNguyên tắc cuối cùng: viết CLAUDE.md như là bạn đang onboard một senior developer mới cực kỳ thông minh nhưng chưa biết gì về project của bạn. Cung cấp đủ context để họ (và Claude) có thể làm việc hiệu quả ngay từ ngày đầu tiên.\u003c\/p\u003e\n\n\u003chr\u003e\n\u003ch3\u003eBài viết liên quan\u003c\/h3\u003e\n\u003cul\u003e\n\u003cli\u003e\u003ca href=\"\/en\/products\/claude-code-vs-github-copilot-vs-cursor-dau-la-ide-ai-t%E1%BB%91t-nh%E1%BA%A5t\"\u003eClaude Code vs GitHub Copilot vs Cursor — Đâu là IDE AI tốt nhất?\u003c\/a\u003e\u003c\/li\u003e\n\u003cli\u003e\u003ca href=\"\/en\/products\/claude-code-toan-t%E1%BA%ADp-l%E1%BA%ADp-trinh-v%E1%BB%9Bi-ai-agent-trong-terminal\"\u003eClaude Code toàn tập — Lập trình với AI agent trong terminal\u003c\/a\u003e\u003c\/li\u003e\n\u003cli\u003e\u003ca href=\"\/en\/products\/context-engineering-ngh%E1%BB%87-thu%E1%BA%ADt-qu%E1%BA%A3n-ly-context-cho-claude\"\u003eContext Engineering — Nghệ thuật quản lý context cho Claude\u003c\/a\u003e\u003c\/li\u003e\n\u003cli\u003e\u003ca href=\"\/en\/products\/claude-cho-engineering-qu%E1%BA%A3n-ly-tech-debt\"\u003eClaude cho Engineering: Quản lý Tech Debt\u003c\/a\u003e\u003c\/li\u003e\n\u003cli\u003e\u003ca href=\"\/en\/products\/best-practices-cho-vision-t%E1%BB%91i-%C6%B0u-hinh-%E1%BA%A3nh-g%E1%BB%ADi-claude\"\u003eBest Practices cho Vision — Tối ưu hình ảnh gửi Claude\u003c\/a\u003e\u003c\/li\u003e\n\u003c\/ul\u003e","brand":"Minh Tuấn","offers":[{"title":"Default Title","offer_id":47721062072532,"sku":null,"price":0.0,"currency_code":"VND","in_stock":true}],"thumbnail_url":"\/\/cdn.shopify.com\/s\/files\/1\/0821\/0264\/9044\/files\/claude-md-masterclass-t_i-_u-workspace-cho-claude-code.jpg?v=1774503996","url":"https:\/\/claude.vn\/en\/products\/claude-md-masterclass-t%e1%bb%91i-%c6%b0u-workspace-cho-claude-code","provider":"CLAUDE.VN","version":"1.0","type":"link"}