From 3e132960594ded0ff9cbdbcd585775201d95c012 Mon Sep 17 00:00:00 2001
From: Michael Drury <me@michaeldrury.co.uk>
Date: Thu, 22 Jan 2026 16:01:28 +0000
Subject: [PATCH] docs: Add Claude Code guidance for workflow traversal and
 prompt building (no-changelog) (#24708)

---
 AGENTS.md                                     | 19 ++++++++
 .../@n8n/ai-workflow-builder.ee/AGENTS.md     | 45 +++++++++++++++++++
 .../@n8n/ai-workflow-builder.ee/CLAUDE.md     |  1 +
 3 files changed, 65 insertions(+)
 create mode 100644 packages/@n8n/ai-workflow-builder.ee/AGENTS.md
 create mode 100644 packages/@n8n/ai-workflow-builder.ee/CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
index d8b19747ea5..1d61fe91a81 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -103,6 +103,25 @@ The monorepo is organized into these key packages:
 - Workflow tests are JSON-based for integration testing
 - AI features have dedicated development workflow (`pnpm dev:ai`)
 
+### Workflow Traversal Utilities
+
+The `n8n-workflow` package exports graph traversal utilities from
+`packages/workflow/src/common/`. Use these instead of custom traversal logic.
+
+**Key concept:** `workflow.connections` is indexed by **source node**.
+To find parent nodes, use `mapConnectionsByDestination()` to invert it first.
+
+```typescript
+import { getParentNodes, getChildNodes, mapConnectionsByDestination } from 'n8n-workflow';
+
+// Finding parent nodes (predecessors) - requires inverted connections
+const connectionsByDestination = mapConnectionsByDestination(workflow.connections);
+const parents = getParentNodes(connectionsByDestination, 'NodeName', 'main', 1);
+
+// Finding child nodes (successors) - uses connections directly
+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
diff --git a/packages/@n8n/ai-workflow-builder.ee/AGENTS.md b/packages/@n8n/ai-workflow-builder.ee/AGENTS.md
new file mode 100644
index 00000000000..b04b985a97d
--- /dev/null
+++ b/packages/@n8n/ai-workflow-builder.ee/AGENTS.md
@@ -0,0 +1,45 @@
+# AGENTS.md
+
+Guidance for working with the AI Workflow Builder package.
+
+## Prompt Development
+
+Use the `PromptBuilder` utility for all LLM prompts. See `src/prompts/README.md`
+for detailed documentation.
+
+```typescript
+import { prompt } from '@/prompts/builder';
+
+const systemPrompt = prompt()
+  .section('role', 'You are an assistant')
+  .sectionIf(hasContext, 'context', () => buildContext())
+  .build();
+```
+
+Key methods:
+- `section(name, content)` - Always included
+- `sectionIf(condition, name, content)` - Conditionally included
+- `examples(name, items, formatter)` - Formatted example list
+- `build()` - Returns the final prompt string
+
+## Workflow Examples in Prompts
+
+When including workflow examples in prompts, use Mermaid flowcharts instead of
+raw JSON. Generate Mermaid from workflow JSON using:
+
+```bash
+pnpm workflow:mermaid path/to/workflow.json
+```
+
+This outputs a markdown file with a Mermaid diagram. The diagram is more
+readable for the LLM and uses fewer tokens than JSON.
+
+Options:
+- `--no-node-name` - Exclude node names
+- `--no-node-type` - Exclude node type comments
+- `--node-params` - Include node parameters
+
+## Evaluations
+
+Before modifying evaluations, judgement criteria, or scoring logic, read
+`evaluations/README.md` for the evaluation framework architecture and guidelines.
\ No newline at end of file
diff --git a/packages/@n8n/ai-workflow-builder.ee/CLAUDE.md b/packages/@n8n/ai-workflow-builder.ee/CLAUDE.md
new file mode 100644
index 00000000000..43c994c2d36
--- /dev/null
+++ b/packages/@n8n/ai-workflow-builder.ee/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md