lcbp3/.devin/rules/08-development-flow.md

trigger

trigger
always_on

Development Flow

🔴 Critical Work — DB / API / Security / Workflow Engine

MUST complete all steps:

1. Glossary check — verify domain terms in 00-02-glossary.md
2. Read the spec — select from Key Spec Files table
3. Check schema — verify table/column in lcbp3-v1.9.0-schema-02-tables.sql
4. Check data dictionary — confirm field meanings + business rules
5. Scan edge cases — 01-06-edge-cases-and-rules.md
6. Check ADRs — verify decisions align (ADR-009, ADR-019, ADR-023)
7. Write code — TypeScript strict, no any, no console.log

🟡 Normal Work — UI / Feature / Integration

• Follow existing patterns in codebase.
• Check spec for relevant module only.
• Hybrid Specs Organization:
  • Place new Infrastructure tasks in specs/100-Infrastructures/
  • Place new Feature/Workflow tasks in specs/200-fullstacks/
  • Place Documentation/Research in specs/300-others/
• Ensure no forbidden patterns (any, console.log, UUID misuse) are introduced.

🟢 Quick Fix — Bug Fix / Typo / Style

• Fix directly
• Add minimal test if logic changed
• Check forbidden patterns before commit

🟢 Specialized Work — ADR-021, AI Runtime Layer, Complex Logic

MUST complete:

1. Domain Knowledge Check - Read relevant ADRs (ADR-021, ADR-023/023A, ADR-024~028)
2. Pattern Verification - Check existing implementations in codebase
3. Specialized Requirements - Follow domain-specific patterns
4. Complex Logic Testing - Multi-scenario test coverage
5. Performance Validation - Load testing if applicable

For ADR-021 Integration:

• Read ADR-021 - Integrated workflow & step attachments
• Check ADR-001 - Unified workflow engine patterns
• Verify WorkflowEngineService - Polymorphic instance handling
• Add workflow fields - Expose workflowInstanceId, workflowState, availableActions
• Include IntegratedBanner - Frontend workflow lifecycle display
• Test workflow transitions - State changes and action validation

For AI Infrastructure (ADR-023/023A):

• Verify AI boundary enforcement - No direct DB/storage access
• Check BullMQ 2-queue setup - ai-realtime + ai-batch
• Validate Qdrant multi-tenancy - projectPublicId filter required
• Test human-in-the-loop validation workflows
• Audit AI interaction logging to ai_audit_logs

For AI Runtime Layer (ADR-024/025/026/027):

• ADR-024: Pattern Layer first (ai_intent_patterns DB + Redis cache 5 min) → LLM Fallback (gemma4:e4b, semaphore max=3)
• ADR-025: Tool Registry dispatch — AI Gateway → Tool → Business Service; ToolResult DTO must use publicId only
• ADR-026: useAiChat() hook + side-panel UI; streaming response via SSE; TanStack Query cache
• ADR-027: Admin Console — dynamic model/prompt/intent control; CASL-guarded admin-only endpoints

For Migration Pipeline (ADR-028):

• Use Staging Queue pattern — never write directly to production tables
• Post-migration cleanup process required after each batch
• Migration Validation Gates must pass before promoting to production

Expected output:

• Backend services expose specialized context fields
• Frontend components use domain-specific patterns
• Complex state management with proper validation
• Performance metrics within acceptable thresholds
• Comprehensive test coverage for edge cases

---

Context-Aware Triggers

Request	Files to Check	Expected Response
"สร้าง API ใหม่"	05-02-backend-guidelines.md, lcbp3-v1.9.0-schema-02-tables.sql	NestJS Controller + Service + DTO + CASL Guard
"แก้ฟอร์ม frontend"	05-03-frontend-guidelines.md, 01-06-edge-cases-and-rules.md	RHF+Zod + TanStack Query + Thai comments
"เพิ่ม field ใหม่"	ADR-009, 03-01-data-dictionary.md, lcbp3-v1.9.0-schema-02-tables.sql	Edit SQL directly + update Data Dictionary + Entity
"ตรวจสอบ UUID"	ADR-019, 05-07-hybrid-uuid-implementation-plan.md	UUIDv7 MariaDB native UUID + TransformInterceptor
"สร้าง migration"	ADR-009, 03-06-migration-business-scope.md	Edit SQL schema directly + n8n workflow
"ตรวจสอบ permission"	lcbp3-v1.9.0-seed-permissions.sql, ADR-016	CASL 4-Level RBAC matrix
"deploy production"	04-08-release-management-policy.md, ADR-015	Release Gates + Blue-Green strategy
"เพิ่ม test"	05-04-testing-strategy.md	Coverage goals + test patterns
"AI integration"	ADR-023, ADR-023A, ADR-024, ADR-025	AI boundary + 2-model stack + BullMQ queue policy + Intent/Tool Layer
"Error handling"	ADR-007	Layered error classification + recovery
"File upload"	ADR-016, 05-02-backend-guidelines.md, 03-Data-and-Storage/03-03-file-storage.md	Two-phase upload → temp → commit; ClamAV + whitelist
"Notifications / Queue"	ADR-008, 05-02-backend-guidelines.md	BullMQ job — never inline; check retry + dead-letter
"Add i18n / translate"	05-08-i18n-guidelines.md	i18n keys only — no hardcoded text
"Workflow / DSL"	ADR-001, 01-03-modules/01-03-06-unified-workflow.md	DSL state machine + WorkflowEngineService
"Document numbering"	ADR-002, 01-02-business-rules/01-02-02-doc-numbering-rules.md	Redis Redlock + DB optimistic lock (double-lock)
"ตรวจสอบ Workflow"	01-06-edge-cases-and-rules.md, 05-02-backend-guidelines.md, ADR-001, ADR-002	เช็คการเปลี่ยน State, คิว BullMQ และการล็อกเลขที่เอกสาร
"Transmittal submit"	ADR-021, specs/200-fullstacks/201-transmittals-circulation/	submit() with EC-RFA-004 validation
"Circulation reassign"	ADR-021, specs/200-fullstacks/201-transmittals-circulation/	reassignRouting() with EC-CIRC-001
"สร้าง workflow ใหม่"	ADR-001, ADR-021, specs/200-fullstacks/203-unified-workflow-engine/	DSL workflow definition + WorkflowEngineService setup
"ตรวจสอบ AI boundary"	ADR-023, ADR-023A	Verify Ollama isolation + BullMQ queues + Qdrant projectPublicId filter
"Intent classification"	ADR-024, specs/200-fullstacks/224-intent-classification/	Pattern Layer → LLM Fallback; ai_intent_patterns; Redis cache 5 min
"AI Tool Layer"	ADR-025, specs/200-fullstacks/225-ai-tool-layer-architecture/	Tool Registry; CASL-guarded dispatch; ToolResult publicId only
"Document Chat UI"	ADR-026, specs/200-fullstacks/226-document-chat-ui-pattern/	Side-panel; useAiChat() hook; streaming SSE; TanStack Query cache
"AI Admin Console"	ADR-027, specs/200-fullstacks/227-ai-admin-console/	Dynamic model/prompt/intent control; admin-only CASL endpoints
"Migration refactor"	ADR-028, specs/200-fullstacks/228-migration-arch-refactor/	Staging Queue; post-migration cleanup; validation gates
"จัดการ document numbering"	ADR-002, specs/03-Data-and-Storage/03-04-document-numbering.md	Redis Redlock + template system + preview/override workflows
"Audit ความปลอดภัย"	ADR-016, ADR-019, ADR-023, ADR-023A	ตรวจสอบ UUID pattern, CASL Guard, AI Boundary และ Qdrant multi-tenancy
"แก้ bug / bugfix"	.agents/workflows/bugfix.md, error-catalog.md	ใช้ bugfix workflow สำหรับเคสที่สาเหตุชัดเจน
"ตรวจแอปจริง"	.windsurf/workflows/check-real-app.md	ตรวจ endpoint/UI/console หลัง build pass — No Fake Evidence
"งานค้าง / resume"	.windsurf/workflows/resume-pending-work.md	อ่าน checkpoint เดิม → ตรวจ build → วางแผนต่อโดยไม่ทำงานซ้ำ

---

🔌 MCP MariaDB Tools

MCP MariaDB server ให้เครื่องมือสำหรับตรวจสอบและจัดการ database โดยตรง ใช้สำหรับ:

• ตรวจสอบ schema กับ spec file specs/03-Data-and-Storage/lcbp3-v1.9.0-schema-02-tables.sql
• Debug ปัญหา database โดยไม่ต้องเข้า MySQL client
• ตรวจสอบ data ใน production/staging
• Validate การเปลี่ยนแปลง schema ก่อน deploy

Available Tools

Tool	หน้าที่	ตัวอย่างการใช้งาน
mcp1_mysql_test_connection	ทดสอบ connection กับ database	ตรวจสอบว่า MCP server เชื่อมต่อได้
mcp1_mysql_show_databases	แสดง databases ทั้งหมด	ดูว่ามี database อะไรบ้าง
mcp1_mysql_show_tables	แสดง tables ทั้งหมดใน database	ดูรายชื่อ tables ใน lcbp3
mcp1_mysql_describe_table	ดู structure/columns ของ table	ตรวจสอบ columns, types, keys ของ correspondences
mcp1_mysql_query	รัน SELECT query	ดู data ใน table หรือ join query
mcp1_mysql_insert	INSERT data	เพิ่ม seed data หรือ test data
mcp1_mysql_update	UPDATE data	แก้ไข data ใน table
mcp1_mysql_delete	DELETE data	ลบ data ใน table

การใช้งานร่วมกับ Development Flow

เมื่อเขียน query ใหม่:

1. ใช้ mcp1_mysql_describe_table เพื่อตรวจสอบ columns และ types
2. เปรียบเทียบกับ specs/03-Data-and-Storage/lcbp3-v1.9.0-schema-02-tables.sql
3. ใช้ mcp1_mysql_query เพื่อทดสอบ query ก่อน implement

เมื่อเปลี่ยน schema (ADR-009):

1. ใช้ mcp1_mysql_describe_table เพื่อดู structure ปัจจุบัน
2. สร้าง SQL delta ใน specs/03-Data-and-Storage/deltas/
3. ใช้ mcp1_mysql_query เพื่อตรวจสอบผลลัพธ์หลัง apply delta

เมื่อ debug ปัญหา database:

1. ใช้ mcp1_mysql_query เพื่อดู data จริง
2. เปรียบเทียบกับ spec และ data dictionary
3. ตรวจสอบ foreign keys และ constraints

ข้อควรระวัง

• ❌ ห้ามใช้ MCP MariaDB สำหรับ DDL operations (CREATE/ALTER/DROP) โดยตรง — ต้องใช้ SQL delta ตาม ADR-009
• ✅ ใช้สำหรับ DQL/DML operations (SELECT/INSERT/UPDATE/DELETE) เพื่อ debug และ test เท่านั้น
• ⚠️ ระวัง DELETE operations — อาจทำให้เสีย data ใน production
• ✅ ตรวจสอบ schema กับ spec file เสมอ ก่อนเขียน query

---

🧠 MCP Memory Tools

MCP Memory server ให้เครื่องมือสำหรับจัดการ Knowledge Graph และ Long-term Memory ใช้สำหรับ:

• จัดเก็บความรู้และ context ของโปรเจกต์ในรูปแบบ Graph (Entities + Relations + Observations)
• ค้นหาและดึงข้อมูล context จาก memory ที่บันทึกไว้ใน session ก่อนหน้า
• สร้าง/แก้ไข/ลบ entities, relations, และ observations ใน knowledge graph

Available Tools

Tool	หน้าที่	ตัวอย่างการใช้งาน
mcp3_create_entities	สร้าง entities ใหม่หลายตัวพร้อม observations	สร้าง entity ใหม่เช่น Project, User, Task
mcp3_create_relations	สร้าง relations ระหว่าง entities	สร้าง relation: Project → has → User
mcp3_add_observations	เพิ่ม observations ให้ entity ที่มีอยู่แล้ว	เพิ่ม context เพิ่มเติมให้ entity
mcp3_delete_entities	ลบ entities และ relations ที่เกี่ยวข้อง	ลบ entity ที่ไม่ใช้แล้ว
mcp3_delete_relations	ลบ relations ระหว่าง entities	ลบ relation ที่ผิดหรือไม่ใช้แล้ว
mcp3_delete_observations	ลบ observations จาก entity	ลบ context ที่ผิดหรือล้าสุด
mcp3_open_nodes	ดึงข้อมูล entities ตามชื่อ	ดึง entity ที่ระบุชื่อ
mcp3_read_graph	อ่าน knowledge graph ทั้งหมด	ดูทั้ง graph structure
mcp3_search_nodes	ค้นหา entities ตาม query	ค้นหา entity จากชื่อ, type, หรือ observation

การใช้งานร่วมกับ Development Flow

เมื่อบันทึก context ใหม่:

1. ใช้ mcp3_create_entities เพื่อสร้าง entities ใหม่ (ถ้ายังไม่มี)
2. ใช้ mcp3_create_relations เพื่อเชื่อมโยง entities
3. ใช้ mcp3_add_observations เพื่อเพิ่ม context/observations

เมื่อค้นหา context:

1. ใช้ mcp3_search_nodes เพื่อค้นหา entities ที่เกี่ยวข้อง
2. ใช้ mcp3_open_nodes เพื่อดึงข้อมูล entities ที่ต้องการ
3. ใช้ mcp3_read_graph เพื่อดู relations ระหว่าง entities

เมื่อแก้ไข context:

1. ใช้ mcp3_add_observations เพื่อเพิ่ม observations ใหม่
2. ใช้ mcp3_delete_observations เพื่อลบ observations ที่ผิด
3. ใช้ mcp3_create_relations หรือ mcp3_delete_relations เพื่อปรับ relations

ข้อควรระวัง

• ✅ ใช้สำหรับบันทึก context ที่ต้องใช้ร่วมกันหลาย session — เช่น การตัดสินใจสำคัญ, architecture decisions, rollout history
• ⚠️ ระวังการลบ entities — อาจทำให้เสีย context ที่ยังใช้งานอยู่
• ✅ ตรวจสอบว่า entity มีอยู่แล้วก่อนสร้าง — ใช้ mcp3_search_nodes หรือ mcp3_open_nodes ก่อน
• ✅ ใช้ชื่อ entity ที่ชัดเจนและไม่ซ้ำกัน — เพื่อป้องกันความสับสน