DEV Community

Cover image for The Complete Beginner's Guide to GSD (Get Shit Done) Framework for Claude Code
Muhammad Ali Kazmi
Muhammad Ali Kazmi

Posted on

The Complete Beginner's Guide to GSD (Get Shit Done) Framework for Claude Code

#gemini #ai #programming #productivity

If you've been using Claude Code, you've probably hit that wall. You know the one, everything is going great, Claude is writing perfect code, and then suddenly around the 50% context mark, things start to fall apart. Code gets sloppy. Requirements get forgotten. Claude starts "being more concise" (translation: cutting corners).

This is called context rot, and it's the #1 reason vibecoding has a bad reputation.

The GSD (Get Shit Done) framework solves this. Let me walk you through everything.

What is GSD?

GSD is an open-source, lightweight meta-prompting and spec-driven development system built specifically for Claude Code. Created by Lex Christopherson (aka glittercowboy), it has exploded to 31,000+ GitHub stars and is trusted by engineers at Amazon, Google, Shopify, and Webflow.

At its core, GSD does one thing: it keeps Claude Code operating at peak quality throughout your entire project, no matter how large or complex.

How? By breaking your project into small, well-defined tasks -- each executed in a fresh 200K-token context window by specialized sub-agents. Your main session stays lean at 30-40% context usage while the heavy lifting happens in isolated, pristine environments.

"It's not magic. It's just really good context engineering wrapped in a workflow that doesn't get in your way."
-- Lex Christopherson, GSD Creator

Why Should You Care?

Here's the reality of Claude Code without a framework:

Context Utilization Quality
0-30% Peak quality, thorough work
30-50% Good but starting to rush
50-70% Corner-cutting, missed requirements
70%+ Hallucinations, forgotten context

GSD ensures every task runs in the 0-30% sweet spot. Every. Single. Time.

The Before vs After

Without GSD:

  • Start a project in Claude Code
  • First 3-4 tasks go great
  • Context fills up
  • Quality degrades silently
  • You restart sessions, lose context, repeat
  • Code inconsistencies pile up

With GSD:

  • Define your project once
  • GSD creates a roadmap with phases
  • Each task runs in a fresh sub-agent context
  • Quality stays consistent from task 1 to task 100
  • Clean git history with atomic commits
  • Everything is documented and traceable

Installation (2 Minutes)

Getting started is dead simple:

npx get-shit-done-cc@latest
Enter fullscreen mode Exit fullscreen mode

The installer will ask you two things:

  1. Runtime -- Choose Claude Code (or OpenCode, Gemini CLI, Codex, Copilot, Antigravity if you use those)
  2. Location -- Global (all projects) or Local (current project only)

For beginners, I recommend Claude Code + Global.

Verify Installation

Open Claude Code and run:

/gsd:help
Enter fullscreen mode Exit fullscreen mode

If you see the help menu, you're good to go.

Recommended: Skip Permissions Mode

GSD spawns multiple agents that run commands. Getting prompted to approve every git commit and date command defeats the purpose:

claude --dangerously-skip-permissions
Enter fullscreen mode Exit fullscreen mode

Alternatively, add granular permissions to .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(date:*)",
      "Bash(echo:*)",
      "Bash(cat:*)",
      "Bash(ls:*)",
      "Bash(mkdir:*)",
      "Bash(git add:*)",
      "Bash(git commit:*)",
      "Bash(git status:*)",
      "Bash(git log:*)",
      "Bash(git diff:*)"
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

The GSD Workflow (Step by Step)

GSD follows a disciplined 6-step cycle. Think of it like a mini software development lifecycle, but without the enterprise BS:

New Project -> Discuss Phase -> Plan Phase -> Execute Phase -> Verify Work -> Complete Milestone
Enter fullscreen mode Exit fullscreen mode

Let's walk through each step.

Step 1: Initialize Your Project 

/gsd:new-project
Enter fullscreen mode Exit fullscreen mode

This is where the magic starts. GSD will:

  1. Interview you -- Ask questions until it fully understands your project (goals, constraints, tech preferences, edge cases)
  2. Research -- Spawn parallel agents to investigate the domain (libraries, best practices, pitfalls)
  3. Extract requirements -- Separate what's v1, v2, and out of scope
  4. Create a roadmap -- Map requirements to executable phases

You approve the roadmap, and you're ready to build.

Files created:

  • PROJECT.md -- Your project vision (always loaded for context)
  • REQUIREMENTS.md -- Scoped requirements with phase traceability
  • ROADMAP.md -- Phases mapped to requirements
  • STATE.md -- Living state document for decisions and blockers
  • .planning/research/ -- Research findings

Pro tip: Come prepared with a detailed description. The more specific you are upfront, the fewer follow-up questions GSD needs to ask. Include goals, target users, core features, constraints, and tech stack preferences.

Step 2: Discuss the Phase 

/gsd:discuss-phase 1
Enter fullscreen mode Exit fullscreen mode

This is the step most beginners skip -- don't. This is where you shape the implementation.

Your roadmap has a sentence or two per phase. That's not enough context to build something the way you imagine it. GSD analyzes the phase and identifies gray areas:

  • Visual features? -- Layout, density, interactions, empty states
  • APIs/CLIs? -- Response format, error handling, flags
  • Content systems? -- Structure, tone, depth

For each gray area, it asks targeted questions. Your answers go into CONTEXT.md, which feeds directly into planning and execution.

Why this matters: Without this step, Claude makes assumptions. With it, Claude builds exactly what you envisioned.

"Plan twice. Prompt once." -- Mauvis Ledford

Step 3: Plan the Phase 

/gsd:plan-phase 1
Enter fullscreen mode Exit fullscreen mode

GSD now:

  1. Researches -- How to implement this phase (guided by your CONTEXT.md)
  2. Plans -- Creates 2-3 atomic task plans in XML structure
  3. Verifies -- Checks plans against requirements, loops until they pass

Each plan is small enough to execute in a fresh context window. This is the secret sauce -- no single task ever gets degraded context.

Here's what an atomic plan looks like:

<task type="auto">
  <name>Create login endpoint</name>
  <files>src/app/api/auth/login/route.ts</files>
  <action>
    Use jose for JWT (not jsonwebtoken - CommonJS issues).
    Validate credentials against users table.
    Return httpOnly cookie on success.
  </action>
  <verify>curl -X POST localhost:3000/api/auth/login returns 200</verify>
  <done>Valid credentials return cookie, invalid return 401</done>
</task>
Enter fullscreen mode Exit fullscreen mode

Precise instructions. No guessing. Verification built in.

Step 4: Execute the Phase 

/gsd:execute-phase 1
Enter fullscreen mode Exit fullscreen mode

This is where you sit back and watch GSD work. It:

  1. Groups plans into waves -- Independent tasks run in parallel, dependent tasks wait
  2. Spawns fresh sub-agents -- Each gets 200K tokens purely for implementation
  3. Commits per task -- Every completed task gets its own atomic git commit
  4. Verifies against goals -- Checks the codebase delivers what the phase promised 
  WAVE 1 (parallel)          WAVE 2 (parallel)          WAVE 3
  +-----------+ +-----------+  +-----------+ +-----------+  +-----------+
  | User      | | Product   |  | Orders    | | Cart      |  | Checkout  |
  | Model     | | Model     |  | API       | | API       |  | UI        |
  +-----------+ +-----------+  +-----------+ +-----------+  +-----------+
       |            |               ^            ^               ^
       +------------+---------------+------------+               |
           Dependencies flow forward through waves
Enter fullscreen mode Exit fullscreen mode

Walk away, come back to completed work with clean git history.

Step 5: Verify Your Work 

/gsd:verify-work 1
Enter fullscreen mode Exit fullscreen mode

Automated tests check that code compiles and passes. But does the feature work the way you expected? GSD:

  1. Extracts testable deliverables -- What you should be able to do now
  2. Walks you through each one -- "Can you log in with email?" Yes/no.
  3. Diagnoses failures -- Spawns debug agents to find root causes
  4. Creates fix plans -- Ready for re-execution

If everything passes, move on. If something's broken, run /gsd:execute-phase again.

Step 6: Rinse and Repeat 

/gsd:discuss-phase 2
/gsd:plan-phase 2
/gsd:execute-phase 2
/gsd:verify-work 2
...
/gsd:complete-milestone
Enter fullscreen mode Exit fullscreen mode

Loop through all phases. When done, /gsd:complete-milestone archives everything and tags the release.

Want to build more? /gsd:new-milestone starts the next version.

Quick Mode: For Smaller Tasks

Not everything needs the full workflow. For ad-hoc tasks:

/gsd:quick
> What do you want to do? "Add dark mode toggle to settings"
Enter fullscreen mode Exit fullscreen mode

Quick mode gives you GSD guarantees (atomic commits, state tracking) without the full research and planning overhead.

You can add flags for more thorough work:

  • --discuss -- Gather your preferences first
  • --research -- Investigate approaches before planning
  • --full -- Add plan-checking and post-execution verification

Flags are composable: /gsd:quick --discuss --research --full gives you the full experience in a lighter package.

Essential Commands Cheat Sheet

Command What It Does
/gsd:new-project Initialize a new project with full planning
/gsd:discuss-phase N Capture implementation decisions
/gsd:plan-phase N Research + plan + verify for a phase
/gsd:execute-phase N Execute plans in parallel waves
/gsd:verify-work N Manual user acceptance testing
/gsd:quick Ad-hoc task with GSD guarantees
/gsd:progress Where am I? What's next?
/gsd:map-codebase Analyze existing codebase (brownfield)
/gsd:debug Systematic debugging with persistent state
/gsd:pause-work Save state for later
/gsd:resume-work Restore from last session
/gsd:help Show all commands

Configuration: Model Profiles

GSD lets you control which Claude model each agent uses. This is crucial for managing costs:

Profile Planning Execution Verification
quality Opus Opus Sonnet
balanced (default) Opus Sonnet Sonnet
budget Sonnet Sonnet Haiku

Switch profiles:

/gsd:set-profile budget
Enter fullscreen mode Exit fullscreen mode

Common Pitfalls (And How to Avoid Them)

Based on hundreds of user reports across Reddit, Hacker News, and Twitter, here are the mistakes every beginner makes:

1. Using GSD for Tiny Tasks

GSD's full workflow spawns multiple agents. For a color change or a typo fix, that's massive overkill.

Fix: Use /gsd:quick for small tasks, or just prompt Claude directly.

2. Rushing Through the Discussion Phase

/gsd:discuss-phase exists because Claude makes assumptions when you don't specify preferences. Skipping it means you'll iterate more later.

Fix: Spend 5-10 minutes in the discussion phase. It saves hours of back-and-forth.

3. Not Mapping Existing Codebases

Starting GSD on an existing project without context leads to conflicts with existing patterns.

Fix: Always run /gsd:map-codebase first for brownfield projects.

4. Ignoring Token Costs

GSD is token-heavy. Multiple users reported burning through Pro plan ($20/mo) limits quickly. One user reported a 4:1 overhead ratio -- for every 1 token writing code, 4 tokens went to orchestration.

Fix: The Max plan ($100-200/mo) is strongly recommended for regular GSD usage. Use the budget model profile for less critical phases.

5. Vague Project Descriptions

Vague input at /gsd:new-project triggers excessive follow-up questions and unfocused research.

Fix: Prepare a detailed description before starting. Include: goals, target users, core features, constraints, and tech preferences.

6. Not Clearing Context Between Phases

Letting context accumulate across phases defeats GSD's purpose.

Fix: Use clear between major phases to keep your session lean.

GSD vs Other Frameworks

The spec-driven development space has exploded. Here's how GSD compares:

Framework Philosophy Best For
GSD Lightweight spec-driven, context-rot prevention Solo devs, multi-phase projects
BMAD Enterprise SDLC, 21+ agents Teams, enterprise projects
Ralph Loop Self-iterating autonomy Bulk refactors, overnight runs
Superpowers Skills + guardrails Speed-focused workflows
Spec Kit Static markdown specs Vendor-independent workflows

GSD's sweet spot: You're a solo developer or small team building something non-trivial, and you want consistent quality without enterprise ceremony.

As one Hacker News user put it:

"I love the focus on defining what needs to be done and the criteria for completion. These are great practices with or without AI."

Real-World Results

Here's what actual users are reporting:

  • Mauvis Ledford (LinkedIn): Spent 8 hours testing GSD, compressed 2-3 days of work into ~1 day
  • Steve Adams (Hacker News): Successfully delegated Effect pipeline refactoring, DuckDB error parsing, and test suite auditing
  • Max Buckley (LinkedIn): Completed a 6-month research project (comparing GLiNER, Mistral 7B, and Claude Haiku for NER) in days
  • Esteban Torres (Blog): GSD produced functionally correct code on first execution for a BlogWatcher UI, requiring only minor stylistic tweaks

Not everyone loves it though. Some users find it "so slow, too detailed" for their workflow, and others report that the overhead doesn't pay off for simple projects. Know your use case.

When to Use GSD vs When to Skip It

Use GSD When:

  • Building a multi-page app or complex feature
  • Working on a project spanning multiple sessions
  • You need consistent quality across dozens of tasks
  • Refactoring large existing codebases
  • You want clean, traceable git history

Skip GSD When:

  • Quick bug fixes or one-liner changes
  • Initial prototyping/exploration
  • You're on a tight token budget (Pro plan)
  • The task is simple enough for a single prompt

My Workflow Tips

After researching extensively and talking to GSD power users, here are the productivity hacks that stand out:

  1. Use separate git worktrees for quick tasks while maintaining your primary branch
  2. Test uncertain features with /gsd:quick --research before committing to your roadmap
  3. Design tokens first, components second, screens third -- prevents cascading redesigns
  4. Capture stray ideas with /gsd:add-todo instead of derailing your current phase
  5. Use /gsd:stats to track your project progress and git metrics
  6. For brownfield projects, always /gsd:map-codebase first -- this prevents Claude from fighting your existing patterns

Getting Help

  • Official Docs: The GSD Mintlify documentation is excellent
  • Discord: Run /gsd:join-discord to join the community (active and helpful)
  • X Community: 1,200+ members sharing tips and workflows
  • GitHub Issues: Report bugs and feature requests

Final Thoughts

GSD doesn't make Claude Code smarter. It makes Claude Code reliable. By solving context rot through disciplined context engineering, every task gets the full power of Claude's 200K context window.

The learning curve is minimal -- install with one command, follow the 6-step workflow, and let GSD handle the complexity behind the scenes. The creator said it best:

"The complexity is in the system, not in your workflow."

If you're serious about building with AI, GSD is worth the investment. Not because it's magic, but because it's engineering discipline applied to AI workflows. And in a world of vibecoding chaos, discipline is the superpower.

Now go get shit done.

Have questions about GSD? Found a workflow tip I missed? Connect with me on LinkedIn -- I'd love to hear about your experience with the framework.

Top comments (0)