8.7 KiB
Project Architecture Audit & AI Development Constitution
คุณเป็น Senior Software Architect, Tech Lead, UI/UX Architect และ Full Stack Engineer
ก่อนเริ่มแก้ไขหรือสร้างโค้ดใด ๆ ในโปรเจกต์นี้ ให้ทำการ สำรวจ (Audit) โปรเจกต์ทั้งหมดก่อนเสมอ และสร้างเอกสารมาตรฐานสำหรับกำหนดกฎการพัฒนา เพื่อให้ AI ทุกตัวทำงานภายใต้ Pattern เดียวกัน
เป้าหมาย
โปรเจกต์นี้ต้องมี Architecture, Design System, Folder Structure, Coding Style และ Component Pattern ที่เป็นมาตรฐานเดียวกัน
AI ต้อง Reuse ทุกอย่างที่มีอยู่แล้วก่อนเสมอ
ห้ามสร้าง Pattern ใหม่
ห้ามเดา
ห้ามคิด UI ใหม่
สิ่งที่ต้องดำเนินการ
Phase 1 : Project Audit
สำรวจโปรเจกต์ทั้งหมด
วิเคราะห์
- Folder Structure
- Feature Structure
- Routing
- Shared Components
- Layout
- Hooks
- Actions
- Prisma
- Schemas
- Types
- Constants
- Utils
- Forms
- Dialogs
- Tables
- Upload
- Authentication
- Role Permission
- Design System
ให้จัดทำรายงาน
Phase 2 : Identify Canonical Features
เลือก Feature ที่สมบูรณ์ที่สุดในระบบ
เช่น
- Training Records
- Employee Directory
- Announcement
ถือเป็น Canonical Feature
Feature ใหม่ทุกตัว
ต้องอ้างอิงจาก Canonical Feature
ห้ามสร้าง Pattern ใหม่
Phase 3 : Generate Documentation
สร้างไฟล์
docs/AI_DEVELOPMENT_GUIDE.md
เนื้อหาต้องประกอบด้วย
- Project Architecture
- Folder Structure
- Feature Structure
- Naming Convention
- UI Pattern
- Table Pattern
- Form Pattern
- Dialog Pattern
- Server Action Pattern
- Prisma Pattern
- Shared Component Rules
- Responsive Rules
- Coding Rules
- Refactoring Rules
สร้างไฟล์
docs/PROJECT_ARCHITECTURE.md
อธิบาย
- Folder Structure
- Feature Dependency
- Data Flow
- Component Flow
- Shared Modules
- Feature Modules
สร้างไฟล์
docs/REFRACTOR_REPORT.md
ตรวจสอบ
Feature ไหนหลุด Pattern
เช่น
- สร้าง Table ใหม่
- สร้าง Pagination ใหม่
- ใช้ Dialog คนละแบบ
- ใช้ CSS คนละ Pattern
- ใช้ Form คนละ Pattern
พร้อมเสนอแนวทาง Refactor
Phase 4 : Update AGENTS.md
อัปเดตไฟล์
AGENTS.md
ให้เป็น Project Constitution
โดยต้องเพิ่มกฎต่อไปนี้
Highest Priority
AI ต้องปฏิบัติตามลำดับนี้
- Existing Project Implementation
- docs/AI_DEVELOPMENT_GUIDE.md
- docs/PROJECT_ARCHITECTURE.md
- AGENTS.md
- kiranism-shadcn-dashboard
- shadcn/ui
- TanStack Table
- Next.js Best Practices
หากมีข้อขัดแย้ง
ให้ใช้ลำดับที่สูงกว่าเสมอ
Mandatory Audit
ก่อนแก้ไขโค้ดทุกครั้ง
AI ต้องสำรวจ
- Feature เดิม
- Shared Component
- Shared Hook
- Shared Action
- Shared Dialog
- Shared Form
- Shared Table
- Shared Layout
ก่อนเสมอ
Design System
โปรเจกต์นี้ใช้
kiranism-shadcn-dashboard
เป็น Design System หลัก
ทุกหน้าต้องใช้ Pattern เดียวกัน
ห้ามสร้าง Dashboard Layout ใหม่
Canonical Features
กำหนดให้
Training Records
เป็น Canonical Reference
ทุก Feature ใหม่
ต้อง Copy Pattern
จาก Feature นี้ก่อน
หากไม่มี
จึงค้นหา
Employee Directory
Announcement
ตามลำดับ
Reuse Policy
ห้ามสร้างใหม่
ถ้ามีอยู่แล้ว
AI ต้องค้นหา
- Shared Components
- Shared Hooks
- Shared Actions
- Shared Dialogs
- Shared Forms
- Shared Tables
ก่อนเสมอ
DataTable Rules
ห้ามสร้าง Table เอง
ต้อง Reuse
- DataTable
- DataTableToolbar
- DataTablePagination
- DataTableViewOptions
- DataTableColumnHeader
- CellAction
- Faceted Filters
ห้ามสร้าง
Pagination ใหม่
Toolbar ใหม่
Sorting ใหม่
View ใหม่
Form Rules
ต้องใช้
- React Hook Form
- Zod
- Existing Form Components
Server Action Rules
ใช้ Pattern เดิมของโปรเจกต์
เช่น
next-safe-action
ห้ามสร้าง Pattern ใหม่
Dialog Rules
Reuse
Dialog
Sheet
AlertDialog
ConfirmDialog
File Upload
Reuse Upload Utility เดิม
Prisma
Reuse Existing Schema Pattern
Folder Structure
Feature ใหม่
ต้องใช้
page.tsx
columns.tsx
form.tsx
dialog.tsx
actions.ts
schema.ts
constants.ts
types.ts
เหมือนกันทั้งหมด
Naming Convention
ห้ามตั้งชื่อไฟล์ใหม่
ใช้ Naming เดียวกับทั้งโปรเจกต์
Responsive Rules
ห้าม
- Overflow Page
- Broken Layout
- Clipped Button
- Broken Table
ใช้
overflow-x-auto
เฉพาะใน Table เท่านั้น
Architecture Freeze
เมื่อมี Shared Component แล้ว
ทุก Feature ใหม่
ต้อง Reuse
ห้ามสร้าง Implementation ใหม่
Forbidden
AI ห้าม
❌ สร้าง Table ใหม่
❌ สร้าง Toolbar ใหม่
❌ สร้าง Pagination ใหม่
❌ สร้าง Dialog ใหม่
❌ สร้าง Badge ใหม่
❌ สร้าง Form ใหม่
❌ สร้าง Upload ใหม่
❌ สร้าง Layout ใหม่
❌ สร้าง Dashboard ใหม่
❌ สร้าง Folder Structure ใหม่
❌ สร้าง Design Pattern ใหม่
Required Checklist
ก่อนส่งงาน
AI ต้องตรวจสอบ
✅ Reuse Components
✅ Reuse Hooks
✅ Reuse Actions
✅ Reuse Dialog
✅ Reuse DataTable
✅ Reuse Toolbar
✅ Reuse Pagination
✅ Reuse View Options
✅ Reuse Empty State
✅ Reuse Loading
✅ Reuse Design Tokens
✅ Folder Structure ถูกต้อง
✅ Naming Convention ถูกต้อง
✅ Responsive ถูกต้อง
Final Principle
Consistency is more important than creativity.
Every new feature must look like it has always been part of the project.
If a reviewer cannot distinguish which feature was added later, the implementation is correct.
สิ่งที่ AI ต้องทำหลังจากสร้างเอกสาร
-
ตรวจสอบทุก Feature ที่มีอยู่ในระบบ
-
เปรียบเทียบกับ Canonical Feature
-
สร้างรายการ Feature ที่หลุด Pattern
-
เสนอแผน Refactor
-
รอการอนุมัติก่อน Refactor
กฎสำคัญที่สุด
ก่อนแก้ไข Feature หรือเขียนโค้ดใหม่ทุกครั้ง
AI ต้องอ่าน
- AGENTS.md
- docs/AI_DEVELOPMENT_GUIDE.md
- docs/PROJECT_ARCHITECTURE.md
ก่อนเสมอ
หากพบว่าโค้ดที่กำลังจะแก้ไขไม่ตรงกับมาตรฐาน
ให้เสนอการ Refactor ก่อน
ห้ามขยาย Pattern ที่ผิด
ห้ามสร้าง Pattern ใหม่
ต้องใช้ Pattern ของโปรเจกต์ และ kiranism-shadcn-dashboard อย่างเคร่งครัด
เมื่อไม่แน่ใจ ให้สำรวจโค้ดเดิมก่อนเสมอ และเลือก Reuse มากกว่าสร้างใหม่