Spec-Graph: Make Your Agent Read the Map Before the Code

Where this fits

A developer drops into a legacy microservices repo, opens a ticket to change checkout logic, and watches their agent burn minutes grep-ing for the right service. The real problem: the agent is reading code before reading the docs that explain why the code exists. The spec-graph skill from JetBrains fixes that by making project specifications—architecture notes, decision records, contracts, boundaries—the first thing your agent consults, organized as a queryable graph.

Why agents benefit

• Context before code: The agent loads the relevant spec graph nodes before touching source files, so it understands intent (e.g., "we chose a saga pattern here because…") instead of reverse-engineering it.
• Contract enforcement: When implementing a feature, the agent can spec_get the interface contracts and check its output against them—catching mismatches before writing a single test.
• Traceable decisions: The graph links decisions to affected modules, so an agent investigating a bug can trace the chain from "why this API exists" to the exact code that implements it.
• Reduced hallucination: With specs as ground truth, the agent grounds its planning in recorded constraints rather than guessing from file names or stale comments.
• Living documentation: The same tools let the agent update specs when it changes behavior, keeping the map in sync with the territory.

Practical scenarios

Onboarding to a new codebase

An agent joins a fresh repository. Instead of listing files, it runs spec_grep "architecture" to load the system overview, then follows graph edges to the service boundaries. It can now propose a change with a mental model that matches the architects' intent.

Planning a cross-module feature

A request touches three services. The agent calls spec_graph to see how those modules are connected, reads the decision records for each, and flags a past constraint that would break the new design—before writing any code.

Investigating a bug with a contract twist

A payment failure is hard to reproduce. The agent reads the spec for the payment API, sees a documented edge case about rounding, and immediately checks the code against that contract—finding the bug in minutes.

Add it to your agent workflow

Install the skill with:

npx skills add JetBrains/thinkrail --skill spec-graph

Then instruct your agent to start any task with the spec tools:

# Example: find the spec node for the checkout module
spec_grep "checkout" --graph

Your agent will read the spec first, then confirm against source. For a deeper look at the tool suite, see the skill page on OpenAgentSkill.

Compare before adopting

Before wiring this in, compare: quality signals—does the project actually maintain rich specs, or are they sparse? Maintenance freshness—check the repo's commit history and star growth (currently 65 stars) to see if the skill is actively evolving. Alternatives—some teams rely on inline docstrings or a monolithic README; if specs are already well-edited, the graph might be overkill. Workflow fit—the skill shines in multi-service repos with explicit decision records, less so in tiny prototypes.

Why it is worth tracking

JetBrains backing gives it credibility, and the ``spec_graph/spec_grep/spec_get` toolset is a deliberate shift from code-first agent behavior to spec-first reasoning. If you're building agents that navigate complex, mature codebases where architecture decisions matter, this skill is worth evaluating today—and if your project's specs are thin, it also nudges you to create them. Keep an eye on its growth; as more teams adopt spec-driven agents, this pattern could become a standard part of agent tooling.