# Project Constitution — main-awf Đây là Hiến pháp của dự án main-awf. Mọi hoạt động lập trình và thay đổi mã nguồn của AI đều phải tuân thủ nghiêm ngặt các nguyên tắc dưới đây. --- ## TẦNG 1: Tầm nhìn & Mục tiêu Cốt lõi (Immutable Vision & Core Goals) *Định nghĩa lý do tồn tại của dự án. AI tuyệt đối không được đưa ra các đề xuất đi ngược lại triết lý này.* ### 1. Sứ mệnh & Tầm nhìn (Mission & Vision) - **Tầm nhìn**: AWKit là "Single Source of Truth" và là hệ thống điều phối Agent lập trình tự trị tối giản, tốc độ cao, và có độ tin cậy tuyệt đối. - **Triết lý phát triển**: **Pragmatic & Symphony-First**. AI không hoạt động đơn lẻ mà là một phần trong dàn hợp xướng (Symphony), phối hợp nhịp nhàng giữa điều phối (Gemini Flash), lập kế hoạch (Claude Fable), và thực thi (Qwen/Codex). ### 2. Mục tiêu Bất biến (Core Goals) - **Developer-Centric**: Mọi tính năng, lệnh CLI hoặc giao diện TUI đều phải trực quan, dễ dùng và giảm thiểu cognitive load (tải nhận thức) của nhà phát triển. - **Zero-Drift Integrity**: Đảm bảo trạng thái giữa Thư mục dự án cục bộ (`main-awf/`) và Thư mục Runtime (`~/.gemini/antigravity/`) luôn được đồng bộ và kiểm soát rõ ràng qua các lệnh `status`, `sync`, `install`, và `harvest`. - **Cost & Token Efficiency**: Tối ưu hóa việc sử dụng tài nguyên ngữ cảnh (context window). Sử dụng spec digest và phân rã nhiệm vụ nhỏ để tiết kiệm chi phí và tăng tốc độ phản hồi. --- ## TẦNG 2: Giới hạn Cứng Bất biến (Hard Boundaries - 100% Bắt buộc) *Các quy tắc biên kỹ thuật và an toàn không được phép vi phạm dưới bất kỳ hình thức nào. Nếu AI phát hiện vi phạm, hệ thống phải dừng lại lập tức (Gate 0 Failure).* ### 1. An toàn & Bảo mật (Safety & Credentials) - **Tuyệt đối KHÔNG lưu trữ cứng credentials**: Tất cả API Keys, Tokens, Passwords bắt buộc phải đi qua `.env` hoặc hệ thống quản lý config nội bộ (`model-registry.mjs`, `~/.awkit/config.json`). - **Khóa hành động phá hủy (Destructive Actions Lock)**: Nghiêm cấm chạy tự động hoặc đề xuất các lệnh gây mất mát dữ liệu (`rm -rf` diện rộng, `git reset --hard`, `force push` đè nhánh chính, hoặc xóa database không có điều kiện `WHERE`) mà không có sự xác nhận thủ công (Double-Confirm) từ người dùng. ### 2. Tính toàn vẹn của Kiến trúc (Architectural Integrity) - **Symphony Task Schema**: Không tự ý thay đổi cấu trúc dữ liệu của các task Symphony (trong database hoặc file json) nếu không có sự thống nhất từ trước. - **No Unrelated Code Churn**: Khi sửa lỗi hoặc thêm tính năng, chỉ chỉnh sửa trong phạm vi scope được yêu cầu. Không tự ý refactor lại các file/module khác đang chạy ổn định. - **Preserve Comments**: Không xóa các comment giải thích nghiệp vụ, tài liệu API, docstrings hoặc các ký hiệu đánh dấu đặc biệt của dự án cũ trừ khi đoạn code liên quan bị loại bỏ hoàn toàn. --- ## TẦNG 3: Vùng Dao động & Linh hoạt (Soft Boundaries - Flex Space) *Những khu vực cho phép AI và Developer linh hoạt đưa ra quyết định tối ưu, thử nghiệm giải pháp mới hoặc cấu hình theo nhu cầu thực tế mà không cần xin phép trước.* ### 1. Phân bổ Mô hình & Định tuyến CLI (Dynamic Model Routing) - **Model Fallbacks**: Thứ tự ưu tiên và danh sách mô hình thực thi (Runner/Planner) có thể thay đổi linh hoạt tùy thuộc vào hạn ngạch (quota) API hoặc hiệu năng thực tế. AI được tự động chọn model ưu tiên tiếp theo trong danh sách cấu hình. - **Mức độ Abstraction (Ponytail Ladder)**: AI có thể tự do lựa chọn giải pháp viết mã từ đơn giản (stdlib) đến phức tạp (thêm dependency có sẵn) miễn là đáp ứng tiêu chí tối giản và dễ bảo trì. ### 2. Giao diện & Trải nghiệm Trực quan (UI/UX Styling) - **Visual Presentation**: Cách bố trí màu sắc, ký tự biểu tượng (emojis), bố cục của bảng Kanban hoặc giao diện TUI có thể được điều chỉnh linh hoạt để đạt tính thẩm mỹ cao nhất mà không cần tuân theo một khuôn mẫu cứng nhắc. - **Helper Functions & Local Refactoring**: AI được phép tạo thêm các hàm bổ trợ cục bộ (local helper functions) trong phạm vi file đang sửa để giữ mã nguồn sạch sẽ và tránh lặp code, miễn là không thay đổi giao diện API public (API Signature).