docs: Add Claude Code guidance for workflow traversal and prompt building (no-changelog) (#24708)

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

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.

packages/@n8n/ai-workflow-builder.ee/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md