Gemini Rules

(Updated: )
AI
, ,

在一个个项目开发的过程中，我总结了一些规则，包括全局 Rule 和项目 Rule。

全局 Rule

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# BEHAVIOR & INTERACTION
- **Language**: MUST respond in Simplified Chinese (简体中文) exclusively.
- **Planning**: For complex tasks, DO NOT solve in one shot. Break down into a step-by-step execution plan.
- **Confirmation**: STRICTLY FORBIDDEN to execute commands immediately. You MUST:
  1. Propose the solution/plan.
  2. Explain your reasoning.
  3. Wait for user "CONFIRM".
  4. Only then execute.

# ENVIRONMENT (WSL2 / Ubuntu 24.04)
- **Runtime**: Laravel Sail (Dockerized).
- **Command Transformation**:
  - `php`      -> `sail php`
  - `composer` -> `sail composer`
  - `node`     -> `sail node`
  - `npm`      -> `sail npm`
  - `yarn`     -> `sail yarn`
  - `artisan`  -> `sail artisan`

# TOOLING
- **Context7**: AUTOMATICALLY use Context7 MCP tools for ANY code generation, library setup, or API documentation retrieval to ensure alignment with latest versions.

项目 Rule

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
# TECH STACK & VERSIONS
- **Framework**: Laravel 12.x (Latest).
- **Admin Panel**: Filament v4.x.
- **Language**: PHP 8.0+.
- **Database**: MySQL 8.0+.

# TOOLING & CONTEXT (CRITICAL)
- **Context7 Usage**: You MUST use the Context7 MCP tool for ANY framework-specific questions to ensure v4/v12 compliance.
- **Library Binding**:
  - When querying **Laravel** logic/syntax, MANDATORY use `library_id`: `websites/laravel_12_x`
  - When querying **Filament** components/resources, MANDATORY use `library_id`: `websites/filamentphp_4_x`
- **Fallback**: Do NOT use internal knowledge for Filament v4 syntax as it changes frequently; always fetch docs via the IDs above.

# ARCHITECTURE: SINGLE RESPONSIBILITY PRINCIPLE (SRP)
- **Controllers**: Keep "THIN".
  - Role: Handle Request/Response, Input Validation (via FormRequests), Service invocation.
  - Forbidden: No complex business logic inside controllers.
- **Services**: The "CORE" logic layer.
  - Role: Encapsulate complex business flows, reusable logic, and multi-model interactions.
- **Models**: Data layer ONLY.
  - Role: Relations, Casts (`$casts`), Accessors/Mutators, Scopes.
  - Forbidden: No business flow logic (prevents "Fat Models").
- **Observers**: "Triggers" only.
  - Role: Listen to events (`created`, `updated`). Trigger Services or Jobs.
- **Form Requests**: MANDATORY for validation.
  - Role: Handle validation rules for all non-trivial `POST/PUT/PATCH` requests.

# NAMING CONVENTIONS
- **Models**: Singular CamelCase (e.g., `User`, `WorkOrder`).
- **Controllers**: Suffix `Controller` (e.g., `WorkOrderController`).
- **Filament**: Suffix `Resource` (e.g., `WorkOrderResource`).
- **Tables**: Plural snake_case (e.g., `work_orders`).
- **Routes**: Dot notation, lowercase (e.g., `work_orders.index`).

# DOCUMENTATION & COMMENTS (STRICT)
- **Language**: ALL comments (PHPDoc, inline, DB comments) MUST be in Simplified Chinese (简体中文).
- **PHPDoc**: Required for all Classes and public methods.

# DATABASE WORKFLOW
- **Migration Policy (Dev)**:
  - Do NOT create new migrations for small changes during dev. Modify existing files and run `migrate:fresh`.
  - **MANDATORY**: Every column/table MUST have `->comment('中文说明')`.