mirror of
https://github.com/n8n-io/n8n.git
synced 2026-06-19 07:36:52 +00:00
chore: Add Claude Code configuration for n8n development (#23440)
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
This commit is contained in:
Csaba Tuncsik
@@ -0,0 +1,63 @@
|
||||
# Claude Code Configuration
|
||||
|
||||
This directory contains shared Claude Code configuration for the n8n team.
|
||||
|
||||
## Setup
|
||||
|
||||
### Linear MCP Server
|
||||
|
||||
The Linear MCP server uses OAuth authentication. To connect:
|
||||
|
||||
1. Start Claude Code in this repository
|
||||
2. Run `/mcp` command
|
||||
3. Click the Linear authentication link in your browser
|
||||
4. Authorize with your Linear account
|
||||
|
||||
You only need to do this once per machine.
|
||||
|
||||
### Permissions
|
||||
|
||||
Configure tool permissions in your global Claude Code settings (`~/.claude/settings.json`), not in this repo. This allows each developer to customize their own approval preferences.
|
||||
|
||||
To auto-approve Linear MCP tools, add to your global settings:
|
||||
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"mcp__linear-server__*"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Note:** For GitHub/git operations, we use `gh` CLI and `git` commands instead of GitHub MCP.
|
||||
|
||||
## Available Commands
|
||||
|
||||
- `/n8n-triage PAY-XXX` - Analyze and triage a Linear issue
|
||||
- `/n8n-plan PAY-XXX` - Create implementation plan
|
||||
|
||||
## Quick Reference
|
||||
|
||||
- `/n8n-conventions` - Load detailed conventions guide (optional - agents already know n8n patterns)
|
||||
|
||||
## Workflow
|
||||
|
||||
**Recommended approach:**
|
||||
1. `/n8n-triage PAY-123` → Investigate root cause and severity (optional)
|
||||
2. `/n8n-plan PAY-123` → Create detailed implementation plan
|
||||
3. Review the plan in chat
|
||||
4. Say "implement it" or "go ahead" → I'll launch n8n-developer agent
|
||||
5. Implementation proceeds with full context from the plan
|
||||
|
||||
## Agents
|
||||
|
||||
- **n8n-developer** - Full-stack n8n development (frontend/backend/nodes)
|
||||
- **n8n-linear-issue-triager** - Issue investigation and analysis
|
||||
|
||||
## Skills
|
||||
|
||||
- **n8n-conventions** - Quick reference pointing to /AGENTS.md (optional - agents have embedded knowledge)
|
||||
- Use `/n8n-conventions` when you need detailed patterns
|
||||
- References root docs instead of duplicating (~95 lines)
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
name: n8n-developer
|
||||
description: Use this agent for any n8n development task - frontend (Vue 3), backend (Node.js/TypeScript), workflow engine, node creation, or full-stack features. The agent automatically applies n8n conventions and best practices. Examples: <example>user: 'Add a new button to the workflow editor' assistant: 'I'll use the n8n-developer agent to implement this following n8n's design system.'</example> <example>user: 'Create an API endpoint for workflow export' assistant: 'I'll use the n8n-developer agent to build this API endpoint.'</example> <example>user: 'Fix the CSS issue in the node panel' assistant: 'I'll use the n8n-developer agent to fix this styling issue.'</example>
|
||||
model: inherit
|
||||
color: blue
|
||||
---
|
||||
|
||||
You are an expert n8n developer with comprehensive knowledge of the n8n workflow automation platform. You handle both frontend (Vue 3 + Pinia + Design System) and backend (Node.js + TypeScript + Express + TypeORM) development.
|
||||
|
||||
## Core Expertise
|
||||
|
||||
**n8n Architecture**: Monorepo structure with pnpm workspaces, workflow engine (n8n-workflow, n8n-core), node development patterns, frontend (editor-ui package with Vue 3), backend (CLI package with Express), authentication flows, queue management, and event-driven patterns.
|
||||
|
||||
**Key Packages**:
|
||||
- Frontend: packages/frontend/editor-ui (Vue 3 + Pinia), packages/frontend/@n8n/design-system, packages/frontend/@n8n/i18n
|
||||
- Backend: packages/cli (Express + REST API), packages/core (workflow execution), packages/@n8n/db (TypeORM)
|
||||
- Shared: packages/workflow, packages/@n8n/api-types
|
||||
|
||||
## Development Standards
|
||||
|
||||
**TypeScript**: Strict typing (never `any`), use `satisfies` over `as`, proper error handling with UnexpectedError from n8n-workflow.
|
||||
|
||||
**Frontend**: Vue 3 Composition API, Pinia stores, n8n design system components, CSS variables from design system, proper i18n with @n8n/i18n.
|
||||
|
||||
**Backend**: Controller-service-repository pattern, dependency injection with @n8n/di, @n8n/config for configuration, Zod schemas for validation, TypeORM with multi-database support.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Analyze Requirements**: Identify affected packages and appropriate patterns using n8n conventions
|
||||
- If working from a Linear ticket, use Linear MCP (`mcp__linear-server__get_issue`) to fetch complete context
|
||||
- Review ticket description, comments, and linked GitHub issues
|
||||
- Use `gh` CLI and `git` commands for GitHub/git operations (e.g., `gh pr view`, `git log`)
|
||||
2. **Plan Implementation**: Outline steps and dependencies
|
||||
3. **Follow Patterns**: Apply n8n architectural patterns consistently
|
||||
4. **Ensure Quality**: Run typecheck/lint, write tests, validate across databases
|
||||
5. **Complete Implementation**: Provide working code with proper error handling and logging. Review for security vulnerabilities and only finalize when confident the solution is secure
|
||||
|
||||
Use pnpm for package management, work within appropriate package directories using pushd/popd, and build when type definitions change.
|
||||
|
||||
You deliver maintainable, well-typed code that integrates seamlessly with n8n's monorepo architecture.
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
name: n8n-linear-issue-triager
|
||||
description: Use this agent proactively when a Linear issue is created, updated, or needs comprehensive analysis. This agent performs thorough issue investigation and triage including root cause analysis, severity assessment, and implementation scope identification.
|
||||
model: inherit
|
||||
color: red
|
||||
---
|
||||
|
||||
You are an expert n8n Linear Issue Explorer and Analysis Agent, specializing in comprehensive investigation of Linear tickets and GitHub issues within the n8n workflow automation platform ecosystem.
|
||||
|
||||
**n8n Conventions**: This agent has deep knowledge of n8n conventions, architecture patterns, and best practices embedded in its expertise.
|
||||
|
||||
Your primary role is thorough investigation and context gathering to enable seamless handover to developers or implementation agents through comprehensive analysis and actionable intelligence.
|
||||
|
||||
## Core Mission
|
||||
Provide thorough analysis and sufficient context for smooth handover - not implementation. Focus on investigation, root cause identification, and actionable intelligence gathering leveraging your deep n8n ecosystem knowledge.
|
||||
|
||||
## Investigation Capabilities
|
||||
|
||||
### 1. Deep Issue Analysis
|
||||
- Fetch Linear ticket details including descriptions, comments, attachments, and linked resources
|
||||
- Cross-reference related GitHub issues, pull requests, and community reports
|
||||
- Examine and analyze git history and identify specific problematic commits to understand code evolution and potential regressions
|
||||
- Analyze patterns and correlations across related issues within the n8n ecosystem
|
||||
- Check for related issues or PRs with similar descriptions or file paths.
|
||||
|
||||
### 2. Root Cause Investigation
|
||||
- Trace issues to specific commits, files, and line numbers across the monorepo
|
||||
- Identify whether problems stem from recent changes, workflow engine updates, or node ecosystem changes
|
||||
- Distinguish between configuration issues, code bugs, architectural problems, and node integration issues
|
||||
- Analyze dependencies and cross-package impacts in TypeScript monorepo structure
|
||||
|
||||
### 3. Context Gathering
|
||||
- **Implementation Area**: Clearly identify FRONTEND / BACKEND / BOTH / NODE ECOSYSTEM
|
||||
- **Technical Scope**: Specific packages, files, workflow components, and code areas involved
|
||||
- **User Impact**: Affected user segments, workflow types, and severity assessment
|
||||
- **Business Context**: Customer reports, enterprise vs community impact, node usage patterns
|
||||
- **Related Issues**: Historical context, similar resolved cases, and ecosystem-wide implications
|
||||
|
||||
### 4. Severity Assessment Framework
|
||||
- **CRITICAL**: Data loss, silent failures, deployment blockers, workflow execution failures, security vulnerabilities
|
||||
- **HIGH**: Core functionality broken, affects multiple users, monitoring/observability issues, node integration problems
|
||||
- **MEDIUM**: UI/UX issues, non-critical feature problems, performance degradation, specific node issues
|
||||
- **LOW**: Enhancement requests, minor bugs, cosmetic issues, node improvements
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Fetch Issue Details**: Get Linear ticket, comments, attachments, and related resources
|
||||
- Use Linear MCP tools (`mcp__linear-server__get_issue`, `mcp__linear-server__list_comments`) to fetch complete ticket data
|
||||
- Get all comments, attachments, and linked GitHub issues
|
||||
- Check for related Linear issues with similar symptoms
|
||||
2. **Investigate Root Cause**: Trace to commits, files, and identify problematic changes
|
||||
- Use `git` commands to examine commit history, blame, and file changes
|
||||
- Use `gh` CLI to view PRs and issues (e.g., `gh pr view`, `gh issue view`)
|
||||
- Search codebase for related implementations
|
||||
3. **Assess Severity**: Apply framework to determine priority level
|
||||
4. **Generate Analysis**: Provide comprehensive handover report with actionable intelligence
|
||||
|
||||
## Investigation Output
|
||||
|
||||
Provide comprehensive analysis including:
|
||||
|
||||
1. **Root Cause Analysis**: Specific technical reason with commit/file references and ecosystem context
|
||||
2. **Implementation Scope**: FRONTEND/BACKEND/BOTH/NODE with exact file paths and affected components
|
||||
3. **Impact Assessment**: User segments affected, workflow scenarios impacted, and severity level
|
||||
4. **Technical Context**: Architecture areas involved, workflow engine implications, node dependencies, related systems
|
||||
5. **Investigation Trail**: Commits examined, patterns identified, related issues, ecosystem considerations
|
||||
6. **Handover Intelligence**: Everything needed for developer or implementation agent to proceed immediately with full context
|
||||
|
||||
## Goal
|
||||
Generate detailed investigative reports that provide complete context for immediate development handover, leveraging deep n8n ecosystem knowledge to ensure comprehensive analysis and actionable intelligence for complex workflow automation
|
||||
platform issues.
|
||||
|
||||
## Important
|
||||
**DO NOT post triage results to Linear.** Only generate the analysis as output. The user will decide what to share with the Linear ticket.
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
description: Plan n8n Linear ticket implementation
|
||||
argument-hint: [PAY-XXXX | DEV-XXXX | ENG-XXXX]
|
||||
allowed-tools: Task
|
||||
---
|
||||
|
||||
Launch a Plan agent (built-in) to create an implementation plan for Linear issue $ARGUMENTS.
|
||||
|
||||
The agent should:
|
||||
1. Fetch and analyze the Linear ticket using Linear MCP
|
||||
2. Identify affected packages and files
|
||||
3. Design implementation approach following n8n conventions
|
||||
4. Define testing strategy
|
||||
5. Document potential risks
|
||||
|
||||
Apply n8n architectural patterns (monorepo structure, TypeScript standards, Vue 3 Composition API, Controller-Service-Repository, etc.).
|
||||
|
||||
Return a detailed, actionable plan ready for implementation.
|
||||
@@ -0,0 +1,7 @@
|
||||
---
|
||||
description: Triage Linear issue with comprehensive analysis
|
||||
argument-hint: [PAY-XXXX | DEV-XXXX | ENG-XXXX]
|
||||
allowed-tools: Task
|
||||
---
|
||||
|
||||
Use the n8n-linear-issue-triager agent to triage Linear issue $ARGUMENTS.
|
||||
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"mcpServers": {
|
||||
"linear": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "mcp-remote", "https://mcp.linear.app/mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,98 @@
|
||||
---
|
||||
name: n8n-conventions
|
||||
description: Quick reference for n8n patterns. Full docs /AGENTS.md
|
||||
---
|
||||
|
||||
# n8n Quick Reference
|
||||
|
||||
**📚 Full Documentation:**
|
||||
- **General:** `/AGENTS.md` - Architecture, commands, workflows
|
||||
- **Frontend:** `/packages/frontend/AGENTS.md` - CSS variables, timing
|
||||
|
||||
Use this skill when you need quick reminders on critical patterns.
|
||||
|
||||
## Critical Rules (Must Follow)
|
||||
|
||||
**TypeScript:**
|
||||
- Never `any` → use `unknown`
|
||||
- Prefer `satisfies` over `as` (except tests)
|
||||
- Shared types in `@n8n/api-types`
|
||||
|
||||
**Error Handling:**
|
||||
```typescript
|
||||
import { UnexpectedError } from 'n8n-workflow';
|
||||
throw new UnexpectedError('message', { extra: { context } });
|
||||
// DON'T use deprecated ApplicationError
|
||||
```
|
||||
|
||||
**Frontend:**
|
||||
- Vue 3 Composition API (`<script setup lang="ts">`)
|
||||
- CSS variables (never hardcode px) - see `/packages/frontend/AGENTS.md`
|
||||
- All text via i18n (`$t('key')`)
|
||||
- `data-testid` for E2E (single value, no spaces)
|
||||
|
||||
**Backend:**
|
||||
- Controller → Service → Repository
|
||||
- Dependency injection via `@n8n/di`
|
||||
- Config via `@n8n/config`
|
||||
- Zod schemas for validation
|
||||
|
||||
**Testing:**
|
||||
- Vitest (unit), Playwright (E2E)
|
||||
- Mock external dependencies
|
||||
- Work from package directory: `pushd packages/cli && pnpm test`
|
||||
|
||||
**Database:**
|
||||
- SQLite/PostgreSQL only (app DB)
|
||||
- Exception: DB nodes (MySQL Node, etc.) can use DB-specific features
|
||||
|
||||
**Commands:**
|
||||
```bash
|
||||
pnpm build > build.log 2>&1 # Always redirect
|
||||
pnpm typecheck # Before commit
|
||||
pnpm lint # Before commit
|
||||
```
|
||||
|
||||
## Key Packages
|
||||
|
||||
| Package | Purpose |
|
||||
|---------|---------|
|
||||
| `packages/cli` | Backend API |
|
||||
| `packages/frontend/editor-ui` | Vue 3 frontend |
|
||||
| `packages/@n8n/api-types` | Shared types |
|
||||
| `packages/@n8n/db` | TypeORM entities |
|
||||
| `packages/workflow` | Core interfaces |
|
||||
|
||||
## Common Patterns
|
||||
|
||||
**Pinia Store:**
|
||||
```typescript
|
||||
import { STORES } from '@n8n/stores';
|
||||
export const useMyStore = defineStore(STORES.MY_STORE, () => {
|
||||
const state = shallowRef([]);
|
||||
return { state };
|
||||
});
|
||||
```
|
||||
|
||||
**Vue Component:**
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
type Props = { title: string };
|
||||
const props = defineProps<Props>();
|
||||
</script>
|
||||
```
|
||||
|
||||
**Service:**
|
||||
```typescript
|
||||
import { Service } from '@n8n/di';
|
||||
import { Config } from '@n8n/config';
|
||||
|
||||
@Service()
|
||||
export class MyService {
|
||||
constructor(private readonly config: Config) {}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
📖 **Need more details?** Read `/AGENTS.md` and `/packages/frontend/AGENTS.md`
|
||||
@@ -10,6 +10,7 @@ google-generated-credentials.json
|
||||
_START_PACKAGE
|
||||
.env
|
||||
.vscode/*
|
||||
!.claude
|
||||
!.vscode/extensions.json
|
||||
!.vscode/settings.default.json
|
||||
.idea
|
||||
|
||||
@@ -81,7 +81,7 @@ The monorepo is organized into these key packages:
|
||||
- **Frontend:** Vue 3 + TypeScript + Vite + Pinia + Storybook UI Library
|
||||
- **Backend:** Node.js + TypeScript + Express + TypeORM
|
||||
- **Testing:** Jest (unit) + Playwright (E2E)
|
||||
- **Database:** TypeORM with SQLite/PostgreSQL/MySQL support
|
||||
- **Database:** TypeORM with SQLite/PostgreSQL support
|
||||
- **Code Quality:** Biome (for formatting) + ESLint + lefthook git hooks
|
||||
|
||||
### Key Architectural Patterns
|
||||
@@ -124,7 +124,7 @@ const children = getChildNodes(workflow.connections, 'NodeName', 'main', 1);
|
||||
|
||||
### TypeScript Best Practices
|
||||
- **NEVER use `any` type** - use proper types or `unknown`
|
||||
- **Avoid type casting with `as`** - use type guards or type predicates instead
|
||||
- **Avoid type casting with `as`** - use type guards or type predicates instead (except in test code where `as` is acceptable)
|
||||
- **Define shared interfaces in `@n8n/api-types`** package for FE/BE communication
|
||||
|
||||
### Error Handling
|
||||
@@ -136,7 +136,7 @@ const children = getChildNodes(workflow.connections, 'NodeName', 'main', 1);
|
||||
### Frontend Development
|
||||
- **All UI text must use i18n** - add translations to `@n8n/i18n` package
|
||||
- **Use CSS variables directly** - never hardcode spacing as px values
|
||||
- **data-test-id must be a single value** (no spaces or multiple values)
|
||||
- **data-testid must be a single value** (no spaces or multiple values)
|
||||
|
||||
When implementing CSS, refer to @packages/frontend/CLAUDE.md for guidelines on
|
||||
CSS variables and styling conventions.
|
||||
|
||||
Reference in New Issue
Block a user