Lesson 07 | GSD Q&A (Part 1): Basic Concepts

From "what is this" to "how do I use it in my project", 20 real questions across 3 chapters.

Chapter 1: Basic Concepts

What GSD is, why you need it, and a breakdown of core concepts.

Q1: What is GSD? How is it different from directly having AI write code?

GSD (Get Shit Done) is a project orchestration framework for Claude Code. Asking AI to just write code is like asking a worker to stack bricks without a plan. GSD = Draw the blueprint first (Requirements) → Schedule it (Roadmap) → Build in stages (Phases) → Inspect each stage (Verification).

Key differences:

• Stateful: The .planning/ directory records all decisions and progress. Close the terminal, open it again, and pick up right where you left off.
• Workflow-driven: Discuss → Plan → Execute → Verify, rather than coding right away.
• Division of labor: 33 sub-agents with specific roles. Researchers research, executors execute, verifiers verify.
• Memory: STATE.md tracks project progress so it never forgets where it's at.

Analogy: Directly writing code is guerrilla warfare; GSD is a regular army.

Q2: I already know how to use Claude Code, do I still need GSD?

It depends on the project size.

You don't need GSD: Fixing a bug, adding a button, writing a script, asking a question.

You need GSD: Starting a new project from scratch, multiple files and phases, unclear requirements, needing tests and verification.

Criteria: If a task can be done in one conversation and doesn't require cross-session memory, just do it. If it spans multiple days and sessions, GSD is worth using.

The calculator project in this tutorial: 3 files but 4 phases, 34 requirements, and 154 tests. You could do it without GSD, but you'd likely forget requirements halfway through or repeat already-made decisions.

Q3: What is the GSD .planning/ directory for? Can I delete it?

.planning/ is GSD's brain. It stores:

• PROJECT.md — Project definition
• REQUIREMENTS.md — Requirements document
• ROADMAP.md — Roadmap
• STATE.md — Current state (where we are, what's next)
• phases/*/CONTEXT.md — Design decisions for each phase (frozen)
• phases/*/PLAN-*.md — Execution plans
• phases/*/VERIFICATION.md — Verification reports
• research/ — Research outputs
• config.json — Workflow configuration

You can delete it. Deleting it won't affect the code already written. But if you delete it, you lose all context—the new session won't know what the project has done, what was decided, or what's next.

Analogy: .planning/ is the construction log. Once the building is done, you can throw it away, but if you need repairs later and lack the log, you have to survey everything from scratch.

Q4: What is CLAUDE.md? Why does GSD read it?

CLAUDE.md is the constraints file in the project root. Claude Code automatically reads it every session.

Example content:

• Tech stack constraints (This project: Pure HTML/CSS/JS, no framework, no backend)
• File constraints (This project: Only 3 files)
• Browser support range
• Accessibility standards
• GSD workflow rules ("Do not edit files directly outside the GSD workflow")

GSD reads it because all sub-agents need to know the project's boundaries. The researcher won't suggest React, the executor won't create a fourth file, and the verifier will check against WCAG AAA standards.

Q5: What is the relationship between GSD and TDD? Do I have to write tests?

GSD does not enforce TDD. But plans generated by /gsd-plan-phase can embed TDD red-green cycles.

Relationship:

• GSD manages the project-level flow (Requirements → Design → Execute → Verify)
• TDD manages the coding-level flow (Test → Implement → Refactor)
• They can be layered: Write code using TDD during GSD's execution phase

This tutorial project opted for TDD, so every task in PLAN.md is "Write test first, then implement." If you don't want tests, /gsd-plan-phase won't force them.

Q6: I don't know how to write a requirements document, can GSD help?

This is exactly one of GSD's core values. /gsd-new-project extracts requirements by asking you questions.

Typical conversation:

• GSD: "Who are your target users?" → You: "Elderly people and regular people."
• GSD: "What special needs do the elderly have?" → You: "Large text, big buttons."
• GSD researches and says: "WCAG AAA requires a 7:1 contrast ratio, did you know that?" → You: "No."
• GSD turns this into structured requirements: ELDR-01 Buttons min 68px, ELDR-02 Contrast ≥ 7:1...

You don't need to know how to write a requirements doc. You just need to describe what you want, and GSD handles the structuring.

Q7: What's the difference between minimal and full installation?

• Minimal installation: 6 core skills, ~700 tokens context overhead. Can do: new-project / plan-phase / execute-phase / verify / quick / debug
• Full installation: 86 skills + 33 sub-agents, ~12k tokens. Can additionally do: AI integrations / UI design contracts / security audits / automated code review fixes / email integration / ...

The calculator project only needed the minimal installation. If your project involves API integrations, complex UI, or security-sensitive scenarios, the full installation is more valuable.

Analogy: Minimal install is a Swiss Army knife; full install is a toolbox.