Anyone who has tried to build large projects using Claude Code, Cursor, or local LLM agents inevitably ran into the context wall 🧱. As soon as the codebase grows beyond a couple of hundred lines, the neural network starts to "forget" the architecture, generate hallucinations, and break the logic of adjacent modules. To make AI work systematically, the industry devised Spec-Driven Development (SDD) - an approach where the agent strictly follows textual specifications. But recently, Steve Yegge (the Amazon and Google veteran) rolled out an alternative - the beads tool, which proposes managing the agent not through prose, but through an explicit dependency graph (DAG). Let's figure out the difference between textual and graph-based planning for AI, and which approach wins in practice.

1. Spec-Driven Development (SDD): The Strength and Weakness of Prose 📝

Popular AI frameworks (e.g., agent-os) promote the classic approach: first think (write spec), then code. Project context is broken down into layers and stored in regular Markdown files:

• 🎯 mission.md - global goal.

• 🗺️ roadmap.md - high-level plan.

• ⚙️ tech-stack.md - stack and constraints. The neural network constantly re-reads these files, tries to interpret the text, and generates concrete steps based on it.

What's the Problem with SDD? 🧐

The weak point of this approach is Control Flow management. The logic of the steps is hidden within the text. The agent must read a paragraph, understand a metaphor or a cause-and-effect relationship, and guess what to do next. As the project becomes more complex, specification files bloat, start consuming precious tokens, and the AI simply "drifts" into hallucinations, confusing the order of tasks.

2. The beads Approach: Task Management via DAG 🔗

The beads tool changes the paradigm. Instead of "spec-first," it offers a "Task-First" approach. Instead of verbose Markdown text, a strict dependency graph is used. The .beads architecture is extremely concise:

• 📋 .beads/issues.jsonl - all tasks in one compact JSON-line file.

• 🗄️ .beads/db.sqlite - local cache for instant queries. Example of one task in issues.jsonl: json { "id": "house-scraper-01", "title": "Implement Web Scraper", "status": "open", "dependencies": [{ "depends_on_id": "auth-module-02" }] }

Here, control flow is explicit. You (or the AI itself during planning) link tasks with rigid graph edges via the CLI: bash bd dep add house-scraper-01 auth-module-02

Now task house-scraper-01 is blocked until auth-module-02 transitions to closed

Killer Feature: bd ready ✨

When you open a new session with Claude Code or another agent, it doesn't need to re-read a 40-page technical specification. It simply executes the bd ready command. The local beads database instantly computes the graph and provides the agent with only those P1 tasks that have no active blockers. The agent will physically not see the parsing task until it writes the authentication module. Context is clean, focus is ideal.

3. Direct Comparison: SDD vs beads 🆚

Criterion	Spec-Driven Development (SDD)	beads workflow
Philosophy	Spec-First. Specification generates code.	Task-First. A graph of tasks drives development.
Control Flow	Implicit. Described in prose in Markdown. The agent interprets the order itself.	Explicit. Defined as a directed graph (DAG). The order is strictly controlled.
Token Consumption	High. Large text files consume the context window.	Minimal. One JSONL line per task. The AI only sees what's currently relevant.
Memory Span	Short memory. Context needs to be "warmed up" again when switching sessions.	Long memory. The project is persisted in a git-native database.
Ideal for...	Designing complex systems where the architectural concept needs to be stabilized first.	Fast and accurate implementation when the general concept of a feature is already clear.

4. What It Looks Like in Practice (Workflow) 🚀

In real life, these approaches can (and should) be hybridized. Here's what an effective application development pipeline with an AI assistant looks like:

1. 🏁 Start: You sketch out a lightweight requirements.md (literally the main use cases and stack). This is your SDD layer.

2. 🌳 Graph Initialization: You ask Claude Code to read this file and decompose it into tasks within beads. The agent itself executes a series of bd issue create and bd dep add commands.

3. 💻 Coding: The text file is shelved. From then on, you and the agent communicate through the lens of the graph: bash

bd ready

Get a list of ready-to-work tasks

bd update house-auth --status=in_progress

Write code...

---

Installation for those who want to try 🛠️

The tool is written in Go and can be installed in seconds.

bash

For macOS (Homebrew)

brew tap steveyegge/beads brew install bd

For Linux / Go environment

go install github.com/steveyegge/beads/cmd/bd@latest

Initialize in the root of your repository

cd my-cool-ai-project bd init

💡 Don't forget to install the official beads plugin for Claude Code so that the agent can work with the CLI out of the box.

Conclusion ✨

SDD is a great tool for an architect, helping to establish the rules of the game. But as an execution engine, text works erratically - AI interprets human language too freely. beads shifts project management to a machine-understandable language - graph theory and compact JSON. It doesn't replace high-level thinking but gives the AI agent the "working memory" and discipline it so sorely lacked in standard chats. How do you manage the context of your AI assistants on large projects? Share your workarounds and practices in the comments! 👇

---

📚 Read also

• The Era of "Vibe-Coding" is Dead: A Complete Guide to Spec-Driven Development (SDD) Frameworks
• Launch of the Beta Version of the Smart Project Estimation Agent
• The Demise of the "Ordinary Senior": Why Your Resume No Longer Reflects Productivity
• Your AI-agent is useless if it doesn't learn
• AI Experience: How to Stop Competing with Thousands of Candidates