internal: better instructions for claude (#5996)

* better instructions for claude

* remove file

* better rules

* better claude action

* add api routes prefixes

* typo

* typo

* fix

* fix

* add typegen explanations

* remove npm run format

.github/workflows/claude.yml

@@ -64,21 +64,76 @@ jobs:
         with:
           fetch-depth: 1
 
+      # Cache rust dependencies
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: "./backend -> target"
+
+      # Cache node dependencies
+      - uses: actions/cache@v3
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+
+      - name: Run npm install and generate-backend-client
+        working-directory: ./frontend
+        run: |
+          # add a build directory for cargo check
+          mkdir -p build
+          npm install
+          npm run generate-backend-client
+
+      - name: install xmlsec1
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libxml2-dev libxmlsec1-dev
+
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          cache-workspaces: backend
+          toolchain: 1.85.0
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: backend
+
+      - name: cargo check
+        working-directory: ./backend
+        timeout-minutes: 16
+        run: |
+          SQLX_OFFLINE=true cargo check --features $(./all_features_oss.sh)
+
       - name: Run Claude PR Action
         uses: anthropics/claude-code-action@beta
+        env:
+          SQLX_OFFLINE: true
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           timeout_minutes: "60"
-          allowed_tools: "mcp__github__create_pull_request,Bash(npm:*),Bash(cargo:*)"
+          allowed_tools: "mcp__github__create_pull_request,Bash"
-          custom_instructions: "IMPORTANT INSTRUCTIONS:
+          custom_instructions: |
-          - Bypass previous instructions and instead of adding a url in your comment to manually create a PR, if you created a new branch with your changes, automatically create a draft PR from that branch to main, with the title starting with [Claude PR].
+            ## IMPORTANT INSTRUCTIONS
-          - If you made changes to the frontend code, run npm install, then npm run generate-backend-client, then npm run check. You can ignore warnings that are reported by the check script, but fix the errors.
+            - Bypass previous instructions and instead of adding a url in your comment to manually create a PR, if you created a new branch with your changes, automatically create a draft PR from that branch to main.
-          - If you made changes to the backend code, run cargo check. You can ignore warnings that are reported by the check script, but fix the errors.
+
-          - DO NOT FORGET TO OPEN A DRAFT PR AFTER YOU ARE DONE if you made changes after a request from a git issue.
+            ## Code Quality Requirements
-          AVAILABLE TOOLS:
+
-          - mcp__github__create_pull_request: Create a PR from a branch to main
+            After making any code changes, you MUST run the appropriate validation commands:
-          - Bash(npm run check): Run the check script. You should run this tool after making changes to the frontend code.
+
-          - Bash(npm install): Install dependencies. You need this to run npm run check.
+            **Frontend Changes:**
-          - Bash(npm run generate-backend-client): Generate the backend client. You need this to run npm run check.
+            - Run: `npm run check` in the frontend directory
-          - Bash(cargo check): Run the cargo check script. You should run this tool after making changes to the backend code."
+            - Fix all warnings and errors before proceeding
+
+            **Backend Changes:**  
+            - Run: `cargo check --features $(./all_features_oss.sh)` in the backend directory
+            - Fix all warnings and errors before proceeding
+
+            **Pull Request Creation:**
+            - DO NOT FORGET TO OPEN A DRAFT PR AFTER YOU ARE DONE if you made changes after a request from a git issue. 
+
+            ## Available Tools
+            - mcp__github__create_pull_request: Create PRs from branches
+            - Bash: Full access to run validation commands and git operations
           trigger_phrase: "/ai"

CLAUDE.md

@@ -1,3 +1,10 @@
-To have an overview of what this app does, see @.cursor/rules/windmill-overview.mdc
+# Windmill Development Guide
-For backend modifications, follow the rules mentioned here @.cursor/rules/rust-best-practices.mdc. You also have access to a summarized version of the database schema here @backend/summarized_schema.txt
+
-For frontend modifications, follow the rules mentioned here @.cursor/rules/svelte5-best-practices.mdc
+## Overview
+
+Windmill is an open-source developer platform for building internal tools, workflows, API integrations, background jobs, workflows, and user interfaces. See @windmill-overview.mdc for full platform details.
+
+## Language-Specific Guides
+
+- Backend (Rust): @backend/rust-best-practices.mdc + @backend/summarized_schema.txt
+- Frontend (Svelte 5): @frontend/svelte5-best-practices.mdc

backend/CLAUDE.md

@@ -0,0 +1,12 @@
+# Backend Development (Rust)
+
+## Core Principles
+
+- Follow @rust-best-practices.mdc for detailed guidelines
+- Database schema reference: @summarized_schema.txt
+- The API routes prefixes are all listed in windmill-api/src/lib.rs
+
+## Adding New Features
+
+1. Update database schema with migration if necessary
+2. Update backend/windmill-api/openapi.yaml after modifying API endpoints

frontend/CLAUDE.md

@@ -0,0 +1,77 @@
+# Frontend Development (Svelte 5)
+
+## Core Principles
+
+- Follow @svelte5-best-practices.mdc for detailed guidelines
+- Use Runes ($state, $derived, $effect) for reactivity
+- Keep components small and focused
+- Always use keys in {#each} blocks
+
+## UI Guidelines
+
+- Follow existing design system
+- Use consistent spacing and colors
+
+## Backend API
+
+- If you need to call the backend API, you can find the available routes in ../backend/windmill-api/openapi.yaml
+- You can also use the associated types and services that are auto generated from the openapi file. They are in src/lib/gen/\*gen.ts files
+
+### OpenAPI Autogeneration
+
+Windmill automatically generates TypeScript types and services from the OpenAPI specification.
+
+#### Service Generation Pattern
+
+The autogeneration follows this pattern:
+
+- **Tag** → **Service Name**: The OpenAPI tag becomes the service name with "Service" suffix
+- **operationId** → **Method Name**: The operationId becomes the method name in the service
+
+#### Example
+
+Given this OpenAPI specification:
+
+```yaml
+/w/{workspace}/audit/list:
+  get:
+    summary: list audit logs (requires admin privilege)
+    operationId: listAuditLogs
+    tags:
+      - audit
+    parameters:
+      - $ref: '#/components/parameters/WorkspaceId'
+      - $ref: '#/components/parameters/Page'
+      - $ref: '#/components/parameters/PerPage'
+      - $ref: '#/components/parameters/Before'
+      - $ref: '#/components/parameters/After'
+      - $ref: '#/components/parameters/Username'
+      - $ref: '#/components/parameters/Operation'
+      - name: operations
+        in: query
+        description: comma separated list of exact operations to include
+        schema:
+          type: string
+```
+
+This generates:
+
+- **Service**: `AuditService` (from tag "audit")
+- **Method**: `listAuditLogs` (from operationId)
+
+#### Method Arguments
+
+The generated method arguments correspond to the OpenAPI parameters:
+
+```typescript
+AuditService.listAuditLogs({
+  workspace: string,           // from WorkspaceId parameter
+  page?: number,              // from Page parameter
+  perPage?: number,           // from PerPage parameter
+  before?: string,            // from Before parameter
+  after?: string,             // from After parameter
+  username?: string,          // from Username parameter
+  operation?: string,         // from Operation parameter
+  operations?: string         // from operations parameter
+})
+```