Cấu trúc thư mục mẫu cho AI Agentic Workspace

Nếu bạn đang dùng Claude, Gemini hay ChatGPT hàng ngày và bắt đầu cảm thấy: thông tin rời rạc, context mất giữa các session, muốn hệ thống hóa công việc lâu dài hơn - thì AI Agentic Workspace là bước tiếp theo đáng nghiên cứu. Bài này chia sẻ cấu trúc thư mục mẫu để bạn có điểm xuất phát cụ thể.

Dùng Claude Projects hay Gemini Gems một thời gian, bạn sẽ nhận ra giới hạn: thông tin vẫn còn rải rác, quy tắc phải nhắc lại mỗi lần, và khi chuyển sang việc phức tạp hơn thì AI không đủ “ngữ cảnh” để hành động đúng. Cảm giác như đang làm việc với một người rất thông minh nhưng hay quên, và bạn phải liên tục nhắc nhở.

AI Agentic Workspace giải quyết vấn đề đó ở tầng cấu trúc - không phải bằng cách viết prompt tốt hơn, mà bằng cách tổ chức workspace để AI luôn có đủ context, biết quy tắc, và có thể tái sử dụng quy trình mà không cần bạn nhắc lại từ đầu mỗi session.

AI Agentic Workspace là gì?

AI Agentic Workspace là môi trường làm việc được thiết kế để AI Agent (như Claude Code) có thể hoạt động tự chủ và nhất quán trên nhiều session.

Khác với việc chat thông thường, một Agentic Workspace có:

• Memory lâu dài - AI nhớ được context, quyết định và tiến độ từ session trước
• Quy tắc cố định - CLAUDE.md và settings.json đảm bảo AI luôn hoạt động đúng chuẩn
• Automation - Hooks chạy tự động khi có sự kiện (mở session, sau khi dùng tool, trước khi nén context)
• Skill library - Quy trình được đóng gói thành Skill, gọi bằng lệnh ngắn thay vì viết prompt dài

Nói đơn giản: thay vì bạn phải “dạy” AI mỗi ngày, workspace giúp AI “tự nhớ” và “tự hành động” đúng cách.

Tại sao cấu trúc thư mục quan trọng?

Với Claude Code, AI đọc file từ thư mục của bạn. Điều đó có nghĩa: cấu trúc thư mục = ngữ cảnh mà AI nhìn thấy.

Nếu thư mục lộn xộn:

• AI không biết file nào quan trọng, file nào là rác
• Không có quy tắc rõ ràng nên output dao động
• Mỗi session phải giải thích lại từ đầu

Nếu thư mục có tổ chức:

• AI load đúng context cần thiết
• Hooks và Settings đảm bảo behavior nhất quán
• Skills giúp tái sử dụng quy trình không cần viết lại prompt

Cấu trúc bên trong .claude/ folder - mỗi subfolder phục vụ một chức năng cụ thể

Cấu trúc thư mục đầy đủ

Đây là cấu trúc workspace mẫu, kết hợp giữa cấp độ project và cấu hình Claude Code:

your-project/
├── CLAUDE.md                      ← Quy tắc dự án (< 200 dòng), AI đọc đầu tiên
├── CLAUDE.local.md                ← Ghi đè cá nhân, bị .gitignore
├── .gitignore
├── .mcp.json                      ← MCP servers, BẮT BUỘC đặt ở root
│
├── .claude/                       ← Não của AI - ưu tiên đọc trước
│   ├── hooks/                     ← Tự động chạy theo sự kiện
│   │   ├── PostToolUse.sh         ← Chạy sau mỗi lần dùng tool
│   │   ├── SessionStart.sh        ← Nạp context khi mở session
│   │   └── PreCompact.sh          ← Lưu trạng thái trước khi nén
│   ├── commands/                  ← Slash command tùy chỉnh /
│   │   └── ship.md                ← Build + lint + deploy trong 1 lệnh
│   ├── skills/                    ← Thư viện Skill, gọi theo ngữ cảnh
│   │   ├── knowledge/
│   │   ├── commit/
│   │   └── ...
│   ├── agents/                    ← Subagent với cửa sổ ngữ cảnh riêng
│   │   ├── code-reviewer.md
│   │   ├── researcher.md
│   │   └── log-analyzer.md
│   ├── rules/                     ← Quy tắc theo đường dẫn file
│   │   └── api.md                 ← Áp dụng riêng cho src/api/**
│   ├── settings.json              ← Quyền, model, đăng ký hooks
│   └── settings.local.json        ← Cá nhân, bị .gitignore
│
├── _client-context/               ← Bối cảnh client/dự án
│   ├── audience.md                ← Mô tả target audience
│   ├── brand-voice.md             ← Giọng điệu thương hiệu
│   └── product-context.md         ← Thông tin sản phẩm
│
├── _sop/                          ← Quy trình chuẩn (Standard Operating Procedures)
│   ├── content-creation.md
│   └── code-review.md
│
├── _memory-logs/                  ← Nhật ký phiên làm việc
│   ├── 2605-log.md
│   └── README.md
│
└── Output/                        ← Kết quả đầu ra
    ├── 260501-project-output.md
    └── README.md

Giải thích từng thành phần

Layer 1: File gốc - nền tảng của mọi thứ

CLAUDE.md là file AI đọc đầu tiên khi khởi động. Đây là nơi bạn viết quy tắc dự án: AI phải làm gì, không được làm gì, code style, ngôn ngữ, và các constraint quan trọng. Giữ dưới 200 dòng - quá dài AI sẽ bỏ qua phần cuối.

CLAUDE.local.md là phiên bản cá nhân, bị .gitignore nên không commit lên git. Dùng để ghi đè quy tắc theo máy hoặc người dùng cụ thể.

.mcp.json khai báo MCP servers - các kết nối cho phép AI truy cập công cụ bên ngoài (Google Analytics, Figma, Notion…). File này phải đặt ở root của project.

Layer 2: .claude/ - não bộ của AI

Đây là thư mục quan trọng nhất. Claude Code ưu tiên đọc .claude/ trước bất kỳ thư mục nào khác.

Hooks chạy tự động theo sự kiện - không cần bạn ra lệnh thủ công

hooks/ chứa shell scripts chạy tự động:

• PostToolUse.sh - Chạy mỗi khi AI dùng một tool (ví dụ: tự commit code sau khi edit file)
• SessionStart.sh - Nạp context dự án khi mở session mới
• PreCompact.sh - Lưu trạng thái trước khi Claude nén conversation

commands/ chứa slash command tùy chỉnh. Tạo file ship.md với nội dung mô tả quy trình, gõ /ship là AI tự chạy build + lint + deploy.

skills/ là thư viện Skill - mỗi Skill là một quy trình được đóng gói. Thay vì viết prompt dài, bạn gọi /knowledge-natecue hay /commit để AI biết cần làm gì.

Skill library giúp tái sử dụng quy trình - gọi bằng slash command thay vì viết prompt từ đầu

agents/ định nghĩa subagent - AI phụ chạy song song với cửa sổ ngữ cảnh riêng biệt. Mỗi file .md trong agents/ là một “nhân vật AI” với chuyên môn riêng: code-reviewer.md, researcher.md, log-analyzer.md.

settings.json kiểm soát quyền hạn của AI: tool nào được phép dùng, model nào được load, hooks nào được đăng ký. File này commit lên git để team dùng chung.

Layer 3: Context layer - bối cảnh dự án

_client-context/ chứa thông tin về client hoặc dự án: audience là ai, brand voice như thế nào, sản phẩm có đặc điểm gì. AI đọc những file này để điều chỉnh output phù hợp với từng dự án.

_sop/ chứa các quy trình chuẩn (Standard Operating Procedures) - hướng dẫn chi tiết AI cần làm gì trong các tình huống cụ thể. Ví dụ: content-creation.md mô tả đúng quy trình viết bài từ research đến publish, code-review.md liệt kê checklist review code. Đây là “sách quy trình” của dự án, tách khỏi .claude/ để dễ chỉnh sửa và chia sẻ với team.

Layer 4: Memory và Output

_memory-logs/ lưu nhật ký phiên làm việc theo ngày. Format chuẩn: ngày giờ, việc đã làm, quyết định quan trọng, vấn đề còn mở, context cần nhớ. AI đọc file này khi bắt đầu session mới để nắm tiến độ.

Output/ chứa kết quả cuối cùng của dự án, đặt tên theo ngày: 260501-project-output.md. Tách khỏi thư mục làm việc để dễ bàn giao.

3 nguyên tắc tổ chức workspace hiệu quả

1. Phân tầng rõ ràng - .claude/ cho cấu hình AI, _client-context/ cho bối cảnh dự án, _memory-logs/ cho lịch sử, Output/ cho kết quả. Mỗi loại thông tin có nơi riêng, không trộn lẫn.

2. Đặt tên bắt đầu bằng _ cho các thư mục meta (context, memory, core). Quy ước này giúp chúng xếp lên đầu trong file explorer và AI hiểu đây là thông tin hỗ trợ, không phải code sản phẩm.

3. Hooks > Prompt - Với những việc lặp lại (auto commit, nạp context, lưu state), viết hook thay vì nhắc AI trong prompt. Hook chạy tự động và nhất quán, prompt thì phụ thuộc vào việc bạn có nhớ nhắc không.

Hướng dẫn setup từ đầu

Đây là cách mình thường bắt đầu một workspace mới - không cần setup hoàn hảo ngay, chỉ cần đủ để chạy được.

Bước 1 - Tạo folder gốc cho project

Tạo một folder mới và đặt tên theo dự án, ví dụ 260508-noi-dung-website hoặc client-abc. Quy ước đặt tên theo ngày (YYMMDD-ten-du-an) giúp dễ sắp xếp khi có nhiều project.

Bước 2 - Tạo các thư mục con cơ bản

Không cần tạo hết ngay. Bắt đầu với 4 folder này là đủ:

your-project/
├── CLAUDE.md
├── _client-context/
├── _memory-logs/
└── Output/

Thêm .claude/ khi bạn sẵn sàng setup hooks và skills. Thêm _sop/ khi có quy trình cần chuẩn hóa.

Bước 3 - Mở folder với công cụ phù hợp

Tùy vào workflow của bạn, có 3 cách:

• Claude Code (CLI) - claude trong terminal từ thư mục gốc. Đây là cách khai thác được toàn bộ sức mạnh: hooks, skills, agents, MCP.
• Obsidian + Claudian - Phù hợp nếu bạn đang dùng Obsidian làm PKM. Claudian plugin cho phép gọi Claude trực tiếp trong vault, thư mục workspace trở thành một phần của knowledge base.
• IDE (Cursor, VS Code) - Mở folder như một project bình thường. Cursor tích hợp Claude nên đọc được CLAUDE.md và context files trong cùng workspace.

Bước 4 - Viết CLAUDE.md

Đây là bước quan trọng nhất. Một CLAUDE.md tối thiểu cần có:

# [Tên dự án]

## Dự án này là gì
[1-2 câu mô tả]

## Quy tắc bắt buộc
- Ngôn ngữ mặc định: [Tiếng Việt / English]
- Tone: [chuyên nghiệp / thân thiện / kỹ thuật]
- Không làm: [những thứ AI không được phép]

## Context quan trọng
- Target audience: [ai đọc output này]
- Đọc _client-context/ trước khi làm bất kỳ task nào

Giữ dưới 200 dòng. Nếu cần thêm quy tắc, tách ra file riêng trong _client-context/ và reference vào.

---

Câu hỏi thường gặp (FAQ)

Nên tạo những folder nào ngay từ đầu?

Bắt đầu với 4 thứ này là đủ để vận hành: CLAUDE.md ở root (viết quy tắc cơ bản của dự án), _client-context/ (audience, brand voice, product context), _memory-logs/ (log sau mỗi session), và Output/ (lưu kết quả bàn giao). Phần .claude/ thêm dần - bắt đầu với settings.json và một SessionStart.sh hook đơn giản là đủ.

.claude/ có nên commit lên git không?

Tùy từng file. settings.json, hooks/, commands/, skills/ nên commit để cả team dùng chung. settings.local.json và CLAUDE.local.md thì .gitignore vì chứa cài đặt cá nhân. Session transcript trong .claude/projects/ cũng nên .gitignore vì có thể chứa code nhạy cảm.

Khác gì so với cách setup Claude Projects thông thường?

Claude Projects (trên claude.ai) là cấu hình qua giao diện web - bạn paste instructions và upload file. Agentic Workspace với Claude Code thì khác hoàn toàn: AI đọc trực tiếp từ file system, hooks chạy tự động, skills có thể gọi bằng lệnh, và AI có quyền thực thi code. Đây là cấp độ autonomy cao hơn nhiều.

Tổng kết

Một AI Agentic Workspace được tổ chức tốt không chỉ giúp AI làm việc hiệu quả hơn - nó thay đổi cả cách bạn nghĩ về làm việc với AI. Thay vì “chat với AI”, bạn “vận hành một hệ thống” - có quy tắc, có memory, có automation. Bắt đầu với CLAUDE.md và một SessionStart.sh hook đơn giản, rồi mở rộng dần theo nhu cầu thực tế.

Liên kết

• Claude Agent và Skill là gì? Hướng dẫn cho người mới bắt đầu
• Quy Trình Build Skill Chuẩn: 7 Bước Tạo AI Skill Hoạt Động Thực Sự
• Context trong AI: Chìa khóa để biến AI từ 'người lạ' thành 'cộng sự
• Optimize AI Chat History: Tự động lưu log, giữ context, tiết kiệm token
• MCP (Model Context Protocol): Chuẩn kết nối AI với thế giới bên ngoài
• SOP là gì? Tại sao cần SOP - đặc biệt khi làm việc với AI Agent