Hướng Dẫn Kỹ Thuật Ngữ Cảnh WSCI & Cấu Trúc Workspace

“Một không gian làm việc sạch sẽ là khởi đầu của một tư duy mạch lạc. Giữa vũ trụ thông tin hỗn độn, WSCI là la bàn định vị của chúng ta.” – Fx Studio

Tài liệu này giải thích chi tiết về khung WSCI (Write-Select-Compress-Isolate) và hướng dẫn thiết lập workspace chuẩn AntiGravity.

1. Khung WSCI Là Gì?

WSCI là chiến lược quản lý “Bộ nhớ ngắn hạn” (Context Window) của AI, giúp ngăn chặn ảo giác và tăng độ chính xác.

W – Write (Viết Rõ Ràng)

• Nguyên tắc: “Code in Context, not just Head”. Đừng giữ yêu cầu trong đầu, hãy viết ra file.
• Thực hành:
  • Sai: Bạn “nhớ” rằng project này dùng Flutter 3.0 và nói với AI “dùng bản mới nhất”.
  • Đúng: Bạn ghi vào AI_CONTEXT.md: Tech Stack: Flutter 3.19.0, Dart 3.3.0.
  • Tạo task.md để theo dõi tiến độ thay vì chat liên tục “đang làm gì rồi?”.

S – Select (Chọn Lọc)

• Nguyên tắc: “Less is More”. Đừng mở 50 tab.
• Thực hành:
  • Sai: Gửi toàn bộ folder src/ cho AI khi chỉ muốn sửa Button Component.
  • Đúng: Chỉ gửi src/components/Button.tsx và src/theme/colors.ts.
  • Dùng .antigravityignore để ẩn các thư mục rác (node_modules, build) khỏi tầm mắt Agent.

C – Compress (Nén Thông Tin)

• Nguyên tắc: “Lossy Compression for AI”.
• Thực hành:
  • Sai: Paste toàn bộ log lỗi dài 2000 dòng.
  • Đúng: Đọc log, copy 5 dòng stack trace quan trọng nhất và mô tả hành vi lỗi.
  • Khi AI cần hiểu kiến trúc dự án lớn, đưa file STRUCTURE.md (chỉ chứa cây thư mục và mô tả) thay vì toàn bộ code.

I – Isolate (Cô Lập Rủi Ro)

• Nguyên tắc: “Sandbox First”.
• Thực hành:
  • Sai: Yêu cầu AI “refactor lại hệ thống auth” trực tiếp trên main branch.
  • Đúng: Yêu cầu AI tạo _playground/auth_experiment/ để thử nghiệm logic mới trước.
  • Cô lập nhiệm vụ: Đừng yêu cầu “Sửa lỗi login và đổi màu logo” trong một prompt. Tách làm hai.

Đọc thêm về triết lý: Kỹ Thuật Ngữ Cảnh (Context Engineering): Khung WSCI Áp Dụng Cho AntiGravity

2. Hướng Dẫn Setup Workspace Chuẩn

Cấu Trúc Thư Mục

Một dự án AntiGravity chuẩn nên có cấu trúc sau:

my-project/
├── .agent/                 # Cấu hình Agent (ẩn)
│   ├── workflows/          # Các quy trình tự động
│   └── skills/             # Các AntiGravity Skills
├── _playground/            # (WSCI Rule: Isolate) Nơi nháp
├── docs/                   # Tài liệu dự án
│   ├── arch/               # Kiến trúc hệ thống
│   └── guides/             # Hướng dẫn sử dụng
├── src/                    # Mã nguồn chính
├── AI_CONTEXT.md           # (WSCI Rule: Write) Ngữ cảnh gốc
├── task.md                 # Quản lý task
└── README.md               # Bản đồ dự án

Checklist Khởi Tạo

1. Tạo thư mục dự án.
2. Tạo AI_CONTEXT.md (Copy mẫu dưới đây).
3. Tạo _playground/.
4. Viết README.md mô tả dự án.

Templates Tham Khảo

Template: AI_CONTEXT.md (Hiến Pháp Dự Án)

# AI_CONTEXT: [Tên Dự Án]

## 1. Project Overview
Mô tả ngắn gọn về dự án: Nó là gì? Giải quyết vấn đề gì? Dành cho ai?

## 2. Tech Stack
*   **Core:** [Language/Framework version]
*   **State Management:** [Lib name]
*   **Database:** [DB name]
*   **Styling:** [Method]

## 3. Architecture Rules
*   [Rule 1]: Ví dụ: Luôn sử dụng Repository Pattern.
*   [Rule 2]: Ví dụ: Không viết business logic trong UI component.
*   [Rule 3]: Ví dụ: Mọi file mới đều phải có header comment.

## 4. Workflows (SOPs)
*   **Debugging:** Trước khi fix, phải đọc log và giải thích nguyên nhân.
*   **Refactoring:** Không thay đổi hành vi bên ngoài (test phải pass).
*   **New Feature:** Phải tạo plan trong `task.md` trước khi code.

## 5. Interaction Rules
*   **Language:** Tiếng Việt (Vietnamese).
*   **Tone:** Chuyên nghiệp, ngắn gọn (The Astronaut style).

Template: README.md (Bản Đồ Dự Án)

# [Tên Dự Án]

> Một câu slogan hoặc mô tả ngắn gọn nhất.

## 📂 Structure Map
*   `src/features`: Chứa các tính năng theo module.
*   `src/shared`: Các component dùng chung.
*   `docs/`: Tài liệu kỹ thuật.
*   `_playground/`: Các thử nghiệm (không deploy).

## 🚀 Quick Start
1.  `npm install`
2.  `npm run dev`

## 🧠 For AI Agents
*   Đọc `AI_CONTEXT.md` để hiểu luật chơi.
*   Kiểm tra `task.md` để biết công việc hiện tại.

Template: task.md (Quản Lý Tiến Độ)

# Task List

## Active Task
- [ ] [WSCI-001] Setup workspace structure <!-- id: 1 -->
- [ ] [WSCI-002] Create AI_CONTEXT.md <!-- id: 2 -->

## Backlog
- [ ] [FE-001] Implement Login Screen
- [ ] [BE-001] Setup NestJS Auth Module

## Context Rules
*   Luôn cập nhật file này sau mỗi task boundary.
*   Dùng `[x]` cho việc đã xong, `[/]` cho việc đang làm.
*   Mỗi item nên có ID để dễ tham chiếu (ví dụ: `[ID-001]`).

3. Hướng Phát Triển Tiếp Theo (Beyond WSCI)

Khung WSCI chỉ là bước khởi đầu để xây dựng một “Agentic Workspace” hoàn chỉnh. Khi bạn đã làm chủ nó, hãy nghĩ đến:

Context-Aware Power-ups

• Metadata Registries: Tạo các file như metadata_apis.md hay metadata_models.md để AI tự tra cứu nhanh mà không cần search code.
• Automated Context updating: Viết script để tự động cập nhật cây thư mục vào STRUCTURE.md mỗi khi có file mới.

Active Knowledge Graph

• Chuyển từ việc lưu trữ tĩnh (files) sang lưu trữ động (knowledge graph) để AI có thể truy vấn mối quan hệ giữa các module (ví dụ: “Module Auth ảnh hưởng đến những module nào?”).

The “Living” Documentation

• Biến document thành một thực thể sống. Thay vì document chết, hãy dùng AI để update document ngay khi code thay đổi (The “Sync” Protocol).

4. Lời Kết: Từ Hỗn Loạn Đến Tinh Gọn

Trong kỷ nguyên AI, ngữ cảnh là tài sản quý giá nhất. Một workspace lộn xộn không chỉ làm chậm tốc độ của bạn mà còn khiến AI bị “mù” giữa biển thông tin.

WSCI không chỉ là kỹ thuật tổ chức file – đó là tư duy thiết kế lại cách chúng ta cộng tác với trí tuệ nhân tạo. Bằng cách Viết rõ ràng, Chọn lọc kỹ, Nén thông tin và Cô lập rủi ro, bạn biến AI từ một công cụ thụ động thành một người đồng nghiệp thấu hiểu dự án như chính bạn.

Hãy bắt đầu ngay hôm nay. Tạo AI_CONTEXT.md đầu tiên của bạn, dọn dẹp lại task.md, và cảm nhận sự khác biệt khi AI trả lời bạn với độ chính xác và chiều sâu hoàn toàn mới.

“Đừng để AI đoán ý bạn. Hãy thiết kế ngữ cảnh để nó không thể hiểu sai.”

Written by chuotfx

Hãy ngồi xuống, uống miếng bánh và ăn miếng trà. Chúng ta cùng nhau đàm đạo về đời, về code nhóe!