I spent 8 hours in GSD. All that time in phases, research documents, architecture diagrams, and .purpose files. At the end? Zero production code. Zero tests. Zero features to actually run and validate.
That's the moment I realized: planning frameworks are designed to help you think clearly, not to become a second full-time job.
So I built something different. A lightweight documentation system called .arc, integrated Claude Code with local RAG search, and learned which AI model to use for which task. The result? Code-first workflows, real feedback loops, and an actual working product.
This is my journey from getting stuck in GSD's beautiful planning spiral to shipping actual features.
The Problem: GSD's Planning Paradox
GSD (Get Shit Done) is genuinely brilliant for complex systems. When you're building something like drug-signal-radar (multi-source medical data aggregation), thinking through architecture, phases, and research upfront saves you from costly refactors later.
But here's what happened to me:
- Phase 1 research: 2 hours (vectors, Qdrant architecture, Pydantic models)
- Phase 1 planning: 3 hours (dependency graphs, integration points, data flows)
- Phase 1 specs: 2 hours (
.purposefiles, validation rules, error handling) - Total: 7 hours. Zero lines of production code.
By hour 8, I'd consumed enough tokens (and personal energy) to implement the entire MVP. The planning framework was so thorough, it became a bottleneck.
The hard truth: planning is valuable until it prevents you from learning what actually works.
The Solution: .arc + Claude Code + Local Models
Instead of abandoning all planning (chaos) or living in it forever (paralysis), I designed something minimal:
What .arc Is
Every project gets a .arc/ folder with 6 lightweight files:
.arc/
├── purpose.md # What does this actor/project do?
├── architecture.md # How is it built internally?
├── instructions.md # Development rules & debugging steps
├── memory.md # Lessons learned (max 250 lines)
├── errors.md # Known issues & fixes
└── security.md # Secrets, validation, compliance
Critical rule: .arc/ is gitignored. It never leaves your machine. It's personal knowledge, not documentation overhead.
Why .arc Wins Over GSD
| Aspect | GSD | .arc |
|---|---|---|
| Time to first code | 6-8 hours | 15 minutes |
| When you start coding | After all planning | During planning |
| Refactor cost | High (phases change everything) | Low (files update as you go) |
| Token cost | Massive (hours of research docs) | Minimal (quick bullets) |
| Living document? | No (static phases) | Yes (evolves with code) |
| Stays in repo? | Yes (clutters GitHub) | No (local only) |
I spend 15 minutes writing .arc/purpose.md and .arc/architecture.md, then immediately start coding. When I learn something new (which is constantly), I update the .arc/ files. No ceremony. No phases. No planning hell.
Claude Code + Local RAG = Instant Codebase Search
Here's what I do when starting work:
- Open Claude Code (the CLI)
- Search my RAG system for similar patterns in my 34 existing repos
- Find working code with exact file paths and line numbers
- Adapt and move on
Instead of remembering "where did I handle retries in that scraper?" or reading through old projects manually, I search in plain English:
"How do I handle rate limiting with exponential backoff across scrapers?"
And get:
pubmed-scraper/src/main.py:142-165 (retry decorator with backoff)
npi-provider-scraper/src/fetcher.py:87-110 (semaphore for concurrent requests)
Cost: Free. All local. Instant.
Intelligent Model Routing: Using the Right Tool
Not every task needs Claude. I built a simple routing system:
Level 1-2: DeepSeek 6.7B (Free, Local)
- Generate a new scraper function
- Syntax fixes, variable renaming
- Create unit tests
- Write input validation
Example: "Generate a Pydantic model for scraper inputs" → DeepSeek nails it in 2 seconds.
Level 3-4: Qwen2.5 14B (Free, Local)
- Write technical blog posts
- Design data parsing pipelines
- Debug async/concurrency issues
- Document architecture decisions
- Explain complex code patterns
Example: "Write a blog post about my RAG system" → Qwen generates the draft, I refine it.
Level 5: Claude API (Real Money)
- System architecture design
- Performance optimization with tradeoffs
- Security/compliance decisions
- When I genuinely need deep reasoning
Example: "Design a multi-source aggregation system that handles 100K+ daily updates" → Claude earns its tokens here.
The rule: Don't use a $20 hammer to hang a $0.10 nail.
Real-Time Monitoring: Token Awareness
I built rat-usage, a dashboard that shows exactly where my tokens go:
$ rat-usage 1 # Last 24 hours
$ rat-usage 7 # Last 7 days
$ rat-web # Open browser dashboard (localhost:8080)
Shows:
- Which models I actually used
- Task breakdown (code vs. blog vs. debug)
- Success/failure rates
- Recent operations with timing
This prevents surprise billing. You see patterns. You notice if you're escalating to Claude unnecessarily.
Waybar Status Line: Cost Awareness in Real-Time
My system panel shows RAG stats constantly:
34 repos 4.0k vectors │ 🖥️ 165 files 250 vectors │ ● online
Click = detailed tooltip. Right-click = Qdrant dashboard. Scroll = refresh.
This takes 2 seconds instead of opening a browser. The cost awareness becomes ambient: you think about it naturally because it's always visible.
A Typical Day Now
Compare the workflows:
Old (GSD-style):
Research (2h) → Design (2h) → Architecture spec (2h) → Finally write code (4h)
↓
Learn design was wrong
↓
Restart (8h wasted)
New (.arc + Claude Code):
Write purpose.md (5min) → Write architecture.md (10min) → Start coding
↓
Learn something mid-way → Update .arc/ files
↓
Commit, test, ship
Feedback loops are tight. Learning is fast. Code exists within an hour.
Key Learnings
Planning has a shelf life. A 1-page
.arc/purpose.mdbeats a 50-page specification. Get to code faster.RAG search is free gold. "Show me how I handle authentication in my scrapers" finds the exact code instantly. No manual digging.
Local models are production-ready. DeepSeek + Qwen handle 95% of my daily work. I reach for Claude only when I genuinely need it.
Visibility prevents waste. Seeing token costs in my status bar changes behavior. Cost optimization happens naturally, not forced.
GSD taught me about architecture. I don't regret those 8 hours: I learned how systems fit together. But now I apply those lessons while coding, not before.
The .arc System in Detail
Every file has a purpose:
purpose.md - Why does this exist? (user-facing)
# Actor: NPI Provider Scraper
Searches the National Provider Identifier (NPI) registry for healthcare providers.
Data sources: nppes.cms.hhs.gov
Users: Healthcare compliance teams, provider directories
architecture.md - How is it built? (technical)
# Architecture
- Async fetcher with rate limiting
- Pydantic models for provider records
- Incremental indexing (skip unchanged providers)
instructions.md - Development rules
# Development Rules
- All API calls must have exponential backoff retry
- Never hardcode API URLs (use environment variables)
- Log API errors but don't log PII
memory.md - Lessons learned (max 250 lines, pruned regularly)
# Lessons Learned
- NPI endpoint rate limits to 150 req/min (learned hard way)
- Provider names change yearly, track `last_updated` field
- Some providers have multiple specialties, normalize to array
errors.md - Known issues
# Known Issues
- Rate limit: Endpoint returns 429 after 150 req/min. Solution: Implement backoff
- Missing fields: Some providers don't have email. Handle gracefully.
security.md - Compliance & secrets
# Security Policy
- API key: Use environment variable, never commit
- PII: Don't log patient data, validate inputs
- HIPAA: Provider data is PHI, encrypt at rest
That's it. No sprawl. Every file has a specific job.
What's Next
- Auto re-index RAG on git hooks (update search instantly)
- Smarter task complexity classification
- Cost tracking baked into Claude Code
Resources
Local Models:
- DeepSeek Coder 6.7B - Code generation
- Qwen 2.5 Coder 14B - Writing & docs
- nomic-embed-text - RAG embeddings (768 dims)
Infrastructure:
- Qdrant - Vector database for RAG
The Bottom Line: Stop letting planning become your work. Use .arc to think clearly, then code immediately. Route to local models. Search with RAG. Watch your costs. Ship fast.
Have questions? Build something with this system? Reach out or comment below. I'm always interested in how others are approaching this problem.