138 lines
7.4 KiB
Markdown
138 lines
7.4 KiB
Markdown
# LCBP3 Agent Rules
|
|
|
|
Critical rules and guidelines for AI agents working on LCBP3-DMS.
|
|
|
|
## Version
|
|
|
|
- **Current:** v1.9.6
|
|
- **Last Updated:** 2026-05-22
|
|
- **Synced with:** `AGENTS.md` (v1.9.6)
|
|
|
|
## Purpose
|
|
|
|
This directory contains rule files that define:
|
|
|
|
- Project context and role expectations
|
|
- Critical Tier 1 rules (CI blockers)
|
|
- Coding standards and patterns
|
|
- Domain terminology and glossary
|
|
- Development workflows
|
|
- Security requirements
|
|
- AI integration architecture (ADR-023/023A)
|
|
|
|
## Rule Enforcement Tiers
|
|
|
|
### 🔴 Tier 1 — CRITICAL (CI BLOCKER)
|
|
|
|
Build fails immediately if violated:
|
|
|
|
- Security (Auth, RBAC, Validation)
|
|
- UUID Strategy (ADR-019) — no `parseInt` / `Number` / `+` on UUID
|
|
- Database correctness — verify schema before writing queries
|
|
- File upload security (ClamAV + whitelist)
|
|
- AI validation boundary (ADR-023)
|
|
- Error handling strategy (ADR-007)
|
|
- Forbidden patterns: `any`, `console.log`, UUID misuse, `id ?? ''` fallback
|
|
|
|
### 🟡 Tier 2 — IMPORTANT (CODE REVIEW)
|
|
|
|
Must fix before merge:
|
|
|
|
- Architecture patterns (thin controller, business logic in service)
|
|
- Test coverage (80%+ business logic, 70%+ backend overall)
|
|
- Cache invalidation
|
|
- Naming conventions
|
|
- TypeScript Standards: Missing JSDoc, explicit types, or file headers
|
|
|
|
### 🟢 Tier 3 — SPECIALIZED WORK
|
|
|
|
Requires domain-specific knowledge:
|
|
|
|
- **ADR-021 Integration:** Workflow Engine & Context implementation
|
|
- **AI Infrastructure:** ADR-023/023A boundary enforcement and pipeline usage
|
|
- **AI Runtime Layer:** ADR-024 Intent Classification, ADR-025 Tool Layer, ADR-026 Chat UI, ADR-027 Admin Console
|
|
- **Migration Pipeline:** ADR-028 Staging Queue & post-migration cleanup
|
|
- **Complex Business Logic:** Multi-step workflows with state management
|
|
- **Performance Optimization:** Database queries, caching strategies, bulk operations
|
|
|
|
### 🔵 Tier 4 — GUIDELINES
|
|
|
|
Best practice — follow when possible:
|
|
|
|
- Code style / formatting (Prettier handles)
|
|
- Comment completeness
|
|
- Minor optimizations
|
|
|
|
## Rule Files
|
|
|
|
### Core Rules (Tier 1 - CRITICAL)
|
|
|
|
| File | Purpose |
|
|
| ----------------------- | ------------------------------------------------------------------------------- |
|
|
| `00-project-context.md` | Project context, role & persona, tier classification, specs folder organization |
|
|
| `01-adr-019-uuid.md` | UUID handling strategy — no parseInt, use publicId only |
|
|
| `02-security.md` | Security requirements, checklist, ADR-023/023A AI boundaries |
|
|
|
|
### Coding Standards
|
|
|
|
| File | Purpose |
|
|
| ------------------------- | ------------------------------------------------------- |
|
|
| `03-typescript.md` | TypeScript rules, file headers, i18n guidelines |
|
|
| `06-backend-patterns.md` | NestJS patterns, UUID resolution, API response patterns |
|
|
| `07-frontend-patterns.md` | Next.js patterns, RHF+Zod+TanStack Query, UUID handling |
|
|
|
|
### Domain & Workflow
|
|
|
|
| File | Purpose |
|
|
| -------------------------- | ------------------------------------------------------------- |
|
|
| `04-domain-terminology.md` | DMS glossary, key spec files priority table |
|
|
| `08-development-flow.md` | Development workflow by work type (Critical/Normal/Quick Fix) |
|
|
|
|
### Compliance & Architecture
|
|
|
|
| File | Purpose |
|
|
| ------------------------- | -------------------------------------------------------------- |
|
|
| `05-forbidden-actions.md` | Actions that must never be done, schema changes, UUID handling |
|
|
| `09-commit-checklist.md` | Pre-commit verification, commit message format |
|
|
| `10-error-handling.md` | ADR-007 error handling strategy, layered classification |
|
|
| `11-ai-integration.md` | ADR-023/023A AI architecture, 2-model stack, BullMQ 2-queue |
|
|
|
|
## Key Spec Files Priority
|
|
|
|
Spec priority: **`06-Decision-Records`** > **`05-Engineering-Guidelines`** > others
|
|
|
|
| Document | Path | Use When |
|
|
| ------------------------------ | --------------------------------------------------------------------------- | --------------------------------- |
|
|
| **Glossary** | `specs/00-overview/00-02-glossary.md` | Verify domain terminology |
|
|
| **Schema Tables** | `specs/03-Data-and-Storage/lcbp3-v1.9.0-schema-02-tables.sql` | Before writing any query |
|
|
| **Data Dictionary** | `specs/03-Data-and-Storage/03-01-data-dictionary.md` | Field meanings + business rules |
|
|
| **Edge Cases** | `specs/01-Requirements/01-06-edge-cases-and-rules.md` | Prevent bugs in flows |
|
|
| **ADR-019 UUID** | `specs/06-Decision-Records/ADR-019-hybrid-identifier-strategy.md` | UUID-related work |
|
|
| **ADR-023 AI** | `specs/06-Decision-Records/ADR-023-unified-ai-architecture.md` | AI integration work |
|
|
| **ADR-023A AI Model** | `specs/06-Decision-Records/ADR-023A-unified-ai-architecture.md` | 2-model stack, BullMQ 2-queue |
|
|
| **ADR-024 Intent Class.** | `specs/06-Decision-Records/ADR-024-intent-classification-strategy.md` | Pattern→LLM Fallback; Redis cache |
|
|
| **ADR-025 AI Tool Layer** | `specs/06-Decision-Records/ADR-025-ai-tool-layer-architecture.md` | Tool Registry; CASL-guarded |
|
|
| **ADR-026 Chat UI** | `specs/06-Decision-Records/ADR-026-document-chat-ui-pattern.md` | Side-panel; streaming SSE |
|
|
| **ADR-027 AI Admin Console** | `specs/06-Decision-Records/ADR-027-ai-admin-console-and-dynamic-control.md` | Dynamic control; admin-only |
|
|
| **ADR-028 Migration Refactor** | `specs/06-Decision-Records/ADR-028-migration-architecture-refactor.md` | Staging Queue; cleanup |
|
|
| **Backend Guidelines** | `specs/05-Engineering-Guidelines/05-02-backend-guidelines.md` | NestJS patterns |
|
|
| **Frontend Guidelines** | `specs/05-Engineering-Guidelines/05-03-frontend-guidelines.md` | Next.js patterns |
|
|
| **Testing Strategy** | `specs/05-Engineering-Guidelines/05-04-testing-strategy.md` | Coverage goals |
|
|
|
|
## Maintenance
|
|
|
|
When updating rules:
|
|
|
|
1. **Check AGENTS.md version** — Ensure rule files are synced
|
|
2. **Update version numbers** — Bump version in `00-project-context.md` only (03-typescript.md no longer has version)
|
|
3. **Review ADR references** — Ensure all ADR references are current (ADR-023, ADR-023A, ADR-024~028)
|
|
4. **Add new forbidden actions** — When new patterns are identified as violations
|
|
5. **Update key spec files table** — When new ADRs or guidelines are added
|
|
6. **Update Tier 3 SPECIALIZED WORK** — When new domain-specific workflows are added
|
|
|
|
## Related Documents
|
|
|
|
- `AGENTS.md` — Master agent configuration and context
|
|
- `specs/06-Decision-Records/` — All Architecture Decision Records
|
|
- `specs/05-Engineering-Guidelines/` — Backend, frontend, and testing guidelines
|