github-mirror/n8n
1
0
Fork 0
mirror of https://github.com/n8n-io/n8n.git synced 2026-05-12 16:10:30 +02:00
Code Issues Actions 15 Packages Projects Releases Wiki Activity
629826ca1d
n8n/packages/@n8n/instance-ai/CLAUDE.md
oleg 629826ca1d
Some checks are pending
Build: Benchmark Image / build (push) Waiting to run
Details
CI: Master (Build, Test, Lint) / Build for Github Cache (push) Waiting to run
Details
CI: Master (Build, Test, Lint) / Unit tests (22.x) (push) Waiting to run
Details
CI: Master (Build, Test, Lint) / Unit tests (24.14.1) (push) Waiting to run
Details
CI: Master (Build, Test, Lint) / Unit tests (25.x) (push) Waiting to run
Details
CI: Master (Build, Test, Lint) / Lint (push) Waiting to run
Details
CI: Master (Build, Test, Lint) / Performance (push) Waiting to run
Details
CI: Master (Build, Test, Lint) / Notify Slack on failure (push) Blocked by required conditions
Details
Util: Sync API Docs / sync-public-api (push) Waiting to run
Details
feat: Instance AI and local gateway modules (no-changelog) (#27206) 
Signed-off-by: Oleg Ivaniv <me@olegivaniv.com>
Co-authored-by: Albert Alises <albert.alises@gmail.com>
Co-authored-by: Jaakko Husso <jaakko@n8n.io>
Co-authored-by: Dimitri Lavrenük <20122620+dlavrenuek@users.noreply.github.com>
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
Co-authored-by: Tuukka Kantola <Tuukkaa@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Mutasem Aldmour <4711238+mutdmour@users.noreply.github.com>
Co-authored-by: Raúl Gómez Morales <raul00gm@gmail.com>
Co-authored-by: Elias Meire <elias@meire.dev>
Co-authored-by: Dimitri Lavrenük <dimitri.lavrenuek@n8n.io>
Co-authored-by: Tomi Turtiainen <10324676+tomi@users.noreply.github.com>
Co-authored-by: Mutasem Aldmour <mutasem@n8n.io>
2026-04-01 21:33:38 +03:00

2.1 KiB
Raw Blame History

Instance AI — Development Guidelines

Linear Tickets

  • Never set priority to Urgent (1). Use High (2) as the maximum.

Engineering Standards

Follow docs/ENGINEERING.md for all implementation work. Key rules:

  • No any, no as casts — use discriminated unions, type guards, satisfies
  • Zod schemas are the source of truth — infer types with z.infer<>, don't define types separately
  • Shared types in @n8n/api-types — event types, API shapes, enums
  • Test behavior, not implementation — test contracts, edge cases, observable outcomes
  • Tools are thin wrappers — validate input, call service, return output. No business logic in tools.
  • Respect the layer boundaries — Tool → Service interface → Adapter → n8n internals

Architecture

Read these docs before starting any implementation:

  • docs/architecture.md — system diagram, deep agent pillars, package responsibilities
  • docs/streaming-protocol.md — canonical event schema, SSE transport, replay rules
  • docs/tools.md — tool reference, orchestration tools, domain tools, tool distribution
  • docs/memory.md — memory tiers, scoping model, sub-agent working memory
  • docs/filesystem-access.md — filesystem architecture, gateway protocol, security model
  • docs/sandboxing.md — Daytona/local sandbox providers, workspace lifecycle, builder loop
  • docs/configuration.md — environment variables, minimal setup, storage, event bus

Key Conventions

  • Event schema: { type, runId, agentId, payload? } — defined in streaming-protocol.md
  • POST /chat/:threadId returns { runId } — not a stream
  • SSE /events/:threadId delivers all events — replay via Last-Event-ID header or ?lastEventId query param
  • Run lifecycle: run-start (first) → events → run-finish (last, carries status)
  • Planned tasks: plan tool for multi-step work; tasks run detached as background agents
  • Sub-agents: stateless, native domain tools only, no MCP, no recursive delegation
  • Memory: working memory = user-scoped, observational memory = thread-scoped