From 9462d56be78c164bfbcc780e7889cef53bf3d062 Mon Sep 17 00:00:00 2001 From: centdix <40307056+centdix@users.noreply.github.com> Date: Thu, 19 Jun 2025 15:36:10 +0200 Subject: [PATCH] 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 | 79 ++++++++++++++++--- CLAUDE.md | 13 ++- backend/CLAUDE.md | 12 +++ .../rules => backend}/rust-best-practices.mdc | 0 frontend/CLAUDE.md | 77 ++++++++++++++++++ .../svelte5-best-practices.mdc | 0 ...mill-overview.mdc => windmill-overview.mdc | 0 7 files changed, 166 insertions(+), 15 deletions(-) create mode 100644 backend/CLAUDE.md rename {.cursor/rules => backend}/rust-best-practices.mdc (100%) create mode 100644 frontend/CLAUDE.md rename {.cursor/rules => frontend}/svelte5-best-practices.mdc (100%) rename .cursor/rules/windmill-overview.mdc => windmill-overview.mdc (100%) diff --git a/.github/workflows/claude.yml b/.github/workflows/claude.yml index 6fee7718a1..26420fd6c1 100644 --- a/.github/workflows/claude.yml +++ b/.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:*)" - custom_instructions: "IMPORTANT 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]. - - 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. - - 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. - AVAILABLE TOOLS: - - mcp__github__create_pull_request: Create a PR from a branch to main - - 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. - - Bash(npm run generate-backend-client): Generate the backend client. You need this to run npm run check. - - Bash(cargo check): Run the cargo check script. You should run this tool after making changes to the backend code." + allowed_tools: "mcp__github__create_pull_request,Bash" + custom_instructions: | + ## IMPORTANT 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. + + ## Code Quality Requirements + + After making any code changes, you MUST run the appropriate validation commands: + + **Frontend Changes:** + - Run: `npm run check` in the frontend directory + - 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" diff --git a/CLAUDE.md b/CLAUDE.md index 5a6512b371..f61e0336be 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,3 +1,10 @@ -To have an overview of what this app does, see @.cursor/rules/windmill-overview.mdc -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 +# Windmill Development Guide + +## 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 diff --git a/backend/CLAUDE.md b/backend/CLAUDE.md new file mode 100644 index 0000000000..1fe509a0d6 --- /dev/null +++ b/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 diff --git a/.cursor/rules/rust-best-practices.mdc b/backend/rust-best-practices.mdc similarity index 100% rename from .cursor/rules/rust-best-practices.mdc rename to backend/rust-best-practices.mdc diff --git a/frontend/CLAUDE.md b/frontend/CLAUDE.md new file mode 100644 index 0000000000..2caad3c0cf --- /dev/null +++ b/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 +}) +``` diff --git a/.cursor/rules/svelte5-best-practices.mdc b/frontend/svelte5-best-practices.mdc similarity index 100% rename from .cursor/rules/svelte5-best-practices.mdc rename to frontend/svelte5-best-practices.mdc diff --git a/.cursor/rules/windmill-overview.mdc b/windmill-overview.mdc similarity index 100% rename from .cursor/rules/windmill-overview.mdc rename to windmill-overview.mdc