Cursor Rules for LangGraph and LangChain Projects

Cursor rules for LangGraph and LangChain projects tell the AI assistant how the graph state is structured, which tools a node may call, how retrieval is implemented, and how to run evaluation tests. These frameworks involve enough non-obvious patterns — conditional edges, stateful graphs, tool callbacks — that an assistant without project-specific rules will produce code that works in isolation but breaks the broader graph.

Tools like fenbs keep the design decisions and lessons from earlier experiments outside the codebase, where they are findable by the next assistant. A decision about why a graph was restructured, a lesson from a tool that returned unexpected output — these belong in fenbs alongside the tasks, not buried in commit messages.

What LangGraph and LangChain rules should cover

• Graph state: the state type definition, which nodes may modify which state fields, and the canonical state update pattern.
• Tool boundaries: which tools each node is allowed to call, and whether a tool may mutate state directly or only return results.
• Retrieval conventions: the retrieval approach (vectorstore, keyword search, hybrid), embedding model, and how documents are chunked and stored.
• Edge conditions: how conditional edges are defined and tested, and which edge conditions are already in production.
• Evaluation: how to run evaluation scripts, which datasets are used, and the minimum score thresholds that pass.
• LLM configuration: which model is used for which node, temperature settings, and whether models may be swapped.

A starting template

# LangGraph project rules

## Setup
- Install: pip install -r requirements.txt
- Test: pytest tests/
- Evaluation: python eval/run_eval.py (ask before running; uses API credits)

## Graph state
- State is defined in src/state.py as a TypedDict.
- Nodes receive and return state; they do not store state externally.
- Only the node responsible for a field may write to it.

## Tools
- Tool definitions are in src/tools/. Do not define tools inline in nodes.
- A tool may only return data; it must not modify graph state directly.
- New tools require a unit test in tests/tools/ before they are used in a node.

## Retrieval
- Use the vectorstore in src/retrieval/store.py. Do not instantiate a new one.
- Chunking config is in src/retrieval/config.py; do not change it without asking.

## LLM configuration
- Model and temperature are set in src/config.py. Do not hardcode model names.
- Ask before changing the model used in any node.

## Evaluation
- Evaluation datasets are in eval/datasets/. Do not modify them.
- A passing run requires a score above the threshold in eval/thresholds.json.

Design decisions from earlier experiments

LangGraph and LangChain projects accumulate design decisions from experiments that did not make it into the code. Why was a particular retrieval approach chosen over another? Why does the graph have a human-in-the-loop node at a specific point? Why was a tool removed? Each of these choices was made for a reason that the current code does not explain.

Recording those decisions in fenbs means the next assistant can read them before it proposes a change. It can ask "is this the retrieval approach we decided to move away from?" instead of proposing it as an improvement. The LangGraph vs CrewAI post compares how both frameworks handle multi-agent coordination if your project spans multiple frameworks.

Lessons from experiments

Evaluation runs and red-teaming produce lessons that are easy to lose. A tool that returned hallucinated data under a specific prompt pattern, a graph edge that caused infinite loops under certain inputs, a chunking size that degraded retrieval quality — these are lessons worth recording, not just fixing.

fenbs Lessons learned are designed for exactly this: what happened, what the team learned, and what to do differently. An assistant that reads the project Lessons before working on retrieval or graph state will not repeat the same mistakes.

How to set up LangGraph rules with fenbs

1. Create a free account and add your LangGraph project to fenbs. Write the key design decisions as Decisions: retrieval approach, graph architecture choices, model selection rationale.
2. Add the template above to your project's .cursor/rules/ directory and fill in your actual file paths, model config locations, and evaluation thresholds.
3. Connect Cursor to fenbs over MCP from Integrations. Ask the assistant to read the project context and lessons before starting on any graph or retrieval work.
4. After each significant experiment, add a Lesson to fenbs: what was tried, what failed, what was learned. The next session reads lessons before starting similar work.

Checkpointing and state persistence

LangGraph supports checkpointing so that a graph can be paused and resumed from any node. An assistant without rules about checkpointing will either ignore it entirely or implement it inconsistently with however the rest of the graph handles persistence. Add a rule about whether the project uses checkpointing, which checkpointer backend is configured, and whether new nodes must be checkpoint-compatible.

If the project does not use checkpointing today but may add it later, note that in fenbs as a Decision rather than the rules file. The rules file captures current conventions; the Decision records that the choice was deliberate and what would prompt a change.

Human-in-the-loop patterns

Human-in-the-loop (HITL) nodes pause a graph and wait for a person to provide input before continuing. An assistant asked to add a new HITL step needs to know the pattern your project uses: which interrupt mechanism, where approval state is stored, and how the graph resumes after input is received. Without these rules, it will pick a pattern from the documentation that may not match the existing graph.

Also specify what happens when a HITL step times out or receives no input. An AI assistant that adds a HITL node without a timeout or fallback path creates a graph that can hang indefinitely. The rules file is the right place to enforce that every HITL step has a defined fallback.

What to watch for

LangGraph and LangChain APIs change frequently across versions. Add the version numbers of both packages to your rules file and note any migration points your project has hit. An assistant that does not know your package versions will use APIs that may not exist in your installed version.

Evaluation runs consume API credits. Make it explicit in the rules that the assistant must ask before running evaluation scripts. The same applies to any test that hits a live model endpoint. A rule that requires approval for credit-consuming commands prevents accidental spend.