The .specify Folder Structure: Anatomy of the Generated Output

Before running your first github spec kit command, it’s important to understand what will be generated — where files are stored, what they contain, and how they relate to each other. This is the foundation for using Spec Kit effectively.

In this article we dissect every file inside the .specify/ folder in detail.

03.1 Complete Structure Overview

Let’s start with the big picture: what a fully-driven feature leaves behind on disk. The tree below shows the constitution, per-feature files, history logs, and templates that Spec Kit produces.

 1santekno-shop/
 2├── .specify/
 3│   ├── constitution.md           ← Project principles (one file for all features)
 4│   ├── features/
 5│   │   └── product-service/
 6│   │       ├── spec.md           ← Business requirements (from specify feature)
 7│   │       ├── clarifications.md ← Clarification answers (from specify clarify)
 8│   │       ├── plan.md           ← Technical plan (from specify plan)
 9│   │       └── tasks.md          ← Task breakdown (from specify tasks)
10│   ├── history/
11│   │   └── *.log                 ← Audit trail of all Spec Kit interactions
12│   └── _templates/
13│       └── spec.md               ← Customizable templates
14└── specify.config.json           ← Project configuration

The takeaway: there are really only a handful of file types here — one constitution, four per-feature documents, logs, and templates — and the rest of this article walks each one in turn.

03.2 constitution.md: The Unchanging Principles

The single most important file in .specify/ is the constitution, because every command reads it as baseline context. To make this concrete, the annotated document below shows the shape of a real Santekno Shop constitution — identity, stack, architecture, and hard rules.

 1# Project Constitution: Santekno Shop
 2# Version: 1.0
 3
 4## Identity
 5Santekno Shop — a B2C e-commerce platform for Indonesia.
 6
 7## Tech Stack
 8- Go 1.22+, Echo v4, PostgreSQL 15 via pgx/v5
 9- Redis 7 via go-redis/v9, Kafka via confluent-kafka-go v2
10- testify/suite + gomock, uuid from github.com/google/uuid
11
12## Architecture: Clean Architecture (STRICT)
13handler → usecase → repository → database
14
15## Must Always
16- fmt.Errorf("function: %w", err) for all error wrapping
17- context.Context as the first parameter everywhere
18- uuid.UUID for IDs (NOT string), prices in cents as int64
19
20## Must Never
21- Any ORM (GORM, Ent, SQLBoiler)
22- Database calls from handler or usecase
23- interface{} / any without strong justification

The defining characteristic to remember: the constitution never mentions a specific feature — it holds only universal principles, which is precisely why every command can safely load it as context.

03.3 features/[name]/spec.md: Business Requirements

Generated by specify feature [name], the spec is deliberately written without any tech stack — it captures what users need, not how to build it. The excerpt below shows the sections a good spec contains.

 1# Feature Specification: Product Catalog
 2## Status: APPROVED   ## Spec Version: v1.2
 3
 4## User Story
 5As a customer browsing Santekno Shop,
 6I want to search and filter products by category and price range,
 7so that I can find products without scrolling through irrelevant items.
 8
 9## Core Capabilities
10- Search by keyword, filter by category and price range
11- Sort by newest / price / popularity
12- "Low stock" warning when stock < 5
13
14## Business Rules
151. A product belongs to exactly one seller
162. Stock cannot go below 0 under any circumstance
173. Deactivated products are invisible in customer search
18
19## Out of Scope (This Phase)
20- Product variants, reviews, bulk import, bundles

Notice what’s absent: there’s no SQL, no HTTP endpoint, and no Go code — all of that appears later in plan.md, keeping the spec a pure statement of intent that a PM can read and approve.

03.4 features/[name]/plan.md: Technical Plan

Generated by specify plan [name], the plan is where the AI turns the spec plus constitution into concrete engineering decisions. The condensed example below shows the artifacts a plan carries.

 1# Technical Implementation Plan: Product Catalog
 2# Based on spec v1.2, constitution v1.0
 3
 4## File Structure to Create
 5internal/product/
 6├── domain/      entity.go, errors.go
 7├── usecase/     interface.go, dto.go, product_usecase.go (+ test)
 8├── repository/  postgres_repository.go (+ integration test)
 9└── handler/     http_handler.go, request.go, response.go (+ test)
10
11## Database Schema (excerpt)
12CREATE TABLE products (
13  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
14  price_cents BIGINT NOT NULL CHECK (price_cents > 0),
15  stock INTEGER NOT NULL DEFAULT 0 CHECK (stock >= 0),
16  status VARCHAR(20) NOT NULL DEFAULT 'ACTIVE'
17);
18
19## API Endpoints
20GET  /api/v1/products            (public)
21POST /api/v1/products            (seller JWT)
22POST /internal/v1/.../deduct-stock (service token)
23
24## Risk Items
25- Indonesian full-text search may need tuning → test with real data
26- Stock deduction race → UPDATE with CHECK constraint + row locking

The plan’s value is that every abstract business rule from the spec now has a technical home — a file, a column, an endpoint, or a documented risk — which is what makes the subsequent task breakdown mechanical rather than creative.

03.5 features/[name]/tasks.md: Actionable Tasks

Generated by specify tasks [name], this file slices the plan into small units, each with a time estimate and a definition of done. The sample below shows the phase-and-task shape.

 1# Task Breakdown: Product Catalog
 2Total: 18 tasks, ~12 hours
 3
 4## Phase 1: Domain Layer [~1.5h]
 5### Task 1.1: Create Product entity [30 min]
 6  File: internal/product/domain/entity.go
 7  Done when: go build ./internal/product/domain/... OK
 8
 9## Phase 2: Repository Layer [~3h]
10### Task 2.5: Implement UpdateStock atomic [40 min]
11  SQL: UPDATE products SET stock = stock - $1
12       WHERE id = $2 AND stock - $1 >= 0
13  Done when: TestUpdateStock_Concurrent_NoNegative passes

The property that makes this useful: every task is small enough to finish in under 90 minutes and carries a concrete “done when,” so implementation becomes a checklist rather than an open-ended session.

03.6 history/: Audit Trail Logs

Every command you run also appends to the history/ folder, giving you a durable record of what happened. The listing below shows a typical set of log files for one feature.

1history/
2├── 2025-07-01T09:00:00-product-service-feature.log
3├── 2025-07-01T09:15:00-product-service-clarify.log
4├── 2025-07-01T09:30:00-product-service-plan.log
5├── 2025-07-01T09:32:00-product-service-tasks.log
6└── 2025-07-01T09:35:00-product-service-implement-phase1.log

Inside any one of those files you get the full accounting of a single call — model, context sizes, timing, and cost. The excerpt below shows one plan run.

1[09:30:00Z] specify plan product-service
2[09:30:00Z] Model: claude-sonnet-4-20250514
3[09:30:00Z] Constitution: constitution.md (1245 chars)
4[09:30:00Z] Spec: product-service/spec.md (2341 chars)
5[09:30:18Z] Response received (18.3s)
6[09:30:18Z] Tokens used: 3,412 prompt + 2,891 completion = 6,303 total
7[09:30:18Z] Cost estimate: $0.019
8[09:30:18Z] Done. Files written: product-service/plan.md

These logs are worth their disk space for three reasons — audit trail (who requested what, when), cost tracking (tokens per command), and debugging (exactly what context reached Claude) — which is why we mine them again in the debugging article.

03.7 Progressive Context Building

The real elegance of Spec Kit is how each command feeds on the outputs of the previous ones. The map below shows what each stage reads and writes.

1specify feature    → reads: nothing      → writes: spec.md
2specify clarify    → reads: spec.md      → writes: spec.md (updated)
3specify plan       → reads: spec + code  → writes: plan.md
4specify tasks      → reads: spec + plan  → writes: tasks.md
5specify implement  → reads: everything   → writes: Go code

The insight to carry forward: context accumulates as you move down the cycle, so by the time implement runs it sees the constitution, spec, plan, and tasks all at once — which is exactly why its output is so much more consistent than a cold prompt.

03.8 specify.config.json: Project Configuration

The one file that lives outside .specify/ is the project config at the repo root, which tunes how the CLI behaves. The example below sets project identity, per-command models, and hooks.

 1{
 2  "project": {
 3    "name": "Santekno Shop",
 4    "language": "go",
 5    "architecture": "clean"
 6  },
 7  "ai": {
 8    "default_model": "claude-sonnet-4-20250514",
 9    "plan_model": "claude-opus-4-6"
10  },
11  "hooks": {
12    "post_implement": "go build ./... && go vet ./..."
13  }
14}

The detail worth noticing: you can assign a stronger model to planning (plan_model) than to everyday commands, spending reasoning budget exactly where the hardest thinking happens.

03.9 What to Commit vs Gitignore

Not everything in .specify/ belongs in version control, so the split matters. The block below shows which files are source of truth and which are local noise.

1# ✅ COMMIT: All Markdown files (source of truth)
2# .specify/constitution.md
3# .specify/features/**/*.md
4# .specify/_templates/**
5
6# ❌ GITIGNORE: Temporary and local files
7echo ".specify/history/" >> .gitignore
8echo ".specify/temp/" >> .gitignore

The rule to internalize: commit every Markdown file because it’s part of your project’s reviewable history, but gitignore history/ since those logs are for local debugging and would otherwise bloat the repo.

03.10 Spec Kit vs Manual SDD File Mapping

If you came from the manual SDD of Topic #1, it helps to see how those artifacts translate. The table below maps each manual file to its Spec Kit equivalent.

The mapping shows Spec Kit isn’t a new paradigm so much as a formalization of manual SDD — the same documents, now generated, named, and located consistently, plus the audit trail you never kept by hand.

03.11 Validating .specify/ Quality

Generated files aren’t automatically good, so it helps to know what “good” looks like for each. The checklist below captures the quality bar per file type.

1Good constitution: no contradictory rules, every rule actionable,
2                   specific tech versions, concrete error-handling example.
3Good spec:         no tech-stack mentions, specific user roles,
4                   measurable business rules, explicit out-of-scope.
5Good plan:         complete file structure, valid SQL,
6                   correct API design, sensible implementation order.
7Good tasks:        each < 90 minutes, concrete "done when",
8                   clear phase dependencies.

Use this as a review rubric: if a generated file fails any line, regenerate or refine it before moving to the next command, since defects compound down the progressive-context chain.

03.12 Syncing .specify/ with CLAUDE.md

Because the constitution and CLAUDE.md overlap, Spec Kit can propagate decisions from one into the other. The commands below preview and then apply the sync.

1# Generate CLAUDE.md updates from the constitution
2specify claude-md sync
3
4# Review the diff, then apply
5specify claude-md sync --apply

The habit to build: review the diff before applying, so an automated sync never silently rewrites the project memory that every Claude Code session depends on.

03.13 Troubleshooting Corrupt Files

Network hiccups during generation can leave a spec or plan incomplete, so Spec Kit ships validation and regeneration commands. The block below validates a feature and regenerates whatever is broken.

1# Validate all spec files
2specify validate --feature=product-service
3
4# Regenerate if corrupt
5specify plan product-service --regenerate
6specify tasks product-service --regenerate

The recovery pattern is reassuringly simple: because every file is regenerable from earlier context, a corrupt plan.md or tasks.md is a one-command fix rather than a manual reconstruction.

03.14 Versioning Spec Files

Specs evolve, so recording their version inline keeps history legible. The metadata block below shows the convention to place at the top of each spec.

1## Metadata
2- Spec Version: v1.2
3- Status: APPROVED
4- Last Updated: 2025-07-01 by @andi
5- Changes from v1.1: Added "low stock" warning rule

Keeping this header current means a reviewer can answer “what changed and why” from the file itself, without archaeology through git blame.

03.15 .specify/ in Monorepos

For a repository hosting several services, the layout nests per-service features under a single shared constitution. The tree below shows that arrangement.

1santekno-shop/                    ← monorepo root
2├── .specify/constitution.md      ← SHARED for all services
3├── services/
4│   ├── order-service/
5│   │   └── .specify/features/    ← Order-specific features
6│   └── product-service/
7│       └── .specify/features/    ← Product-specific features

The principle: one constitution governs the whole monorepo while each service owns only its own feature specs — the same “global rules, local features” split we saw in single-repo projects, and a topic we expand in Article 17.

03.16 Reading Order for New Team Members

The folder doubles as onboarding material, but only if read in the right order. The list below is the sequence that gets a new engineer productive fastest.

11. constitution.md      → understand project principles
22. features/*/spec.md   → understand what we're building
33. features/*/plan.md   → understand how we'll build it
44. features/*/tasks.md  → understand what's done / pending
55. the code             → implementation details last

Reading in this order — principles, then intent, then design, then code — is dramatically more efficient than diving into source first, because each layer frames the next.

03.17 Template Customization

Teams often want a house style for specs, which is what the _templates/ folder enables. The commands below copy the default template and use a custom one.

1# Copy and modify the default template
2cp .specify/_templates/spec.md .specify/_templates/spec-custom.md
3
4# Use the custom template for a new feature
5specify feature new-feature --template=spec-custom

Team-specific templates enforce a consistent spec shape across everyone — but as the gotchas below note, changing a template affects every future feature, so treat it as a reviewed change.

03.18 Tips & Gotchas

A handful of lessons keep the .specify/ folder healthy over the long run:

💡 Tip 1: Read plan.md before tasks.md — the plan provides big-picture context for why the tasks are organized as they are.

💡 Tip 2: History logs are a gold mine for debugging — check what context was sent to Claude when output is unexpected.

💡 Tip 3: The constitution is a living document — update it whenever there’s a new architectural decision.

💡 Tip 4: Read clarifications.md after specify clarify — it documents why certain spec decisions were made.

⚠️ Gotcha 1: Don’t manually edit plan.md or tasks.md — regenerate instead to avoid inconsistencies.

⚠️ Gotcha 2: The history folder can grow large — set up log rotation or gitignore it.

⚠️ Gotcha 3: spec.md and plan.md must stay in sync — if the spec changes, regenerate the plan.

⚠️ Gotcha 4: Template overrides affect all future features — ensure team review before changing templates.

The unifying theme: let the tooling own the generated files and reserve your manual edits for the human-authored ones — spec intent and the constitution — so the progressive-context chain never goes out of sync.

03.19 Inspecting Spec Kit Output

Finally, a few shell one-liners turn the folder into something you can query. The commands below list files, total token usage, and cost estimates.

1# List all .specify/ files
2find .specify/ -type f -name "*.md" | sort
3
4# Track total token usage
5grep "Tokens used:" .specify/history/*.log | awk '{sum += $NF} END {print "Total:", sum}'
6
7# View cost estimates
8grep "Cost estimate:" .specify/history/*.log

The payoff: because every interaction is logged in a grep-friendly format, questions like “how much has this feature cost so far?” become a single pipeline rather than guesswork.

03.20 Summary

The .specify/ folder is your “project memory,” stored as committable, reviewable, versionable Markdown files.

Four main files: constitution.md (universal principles), spec.md (business requirements), plan.md (technical plan), tasks.md (action items).

Progressive context building: Each command reads all previous outputs, making context richer and output more relevant as you move down the cycle.

Commit all Markdown, gitignore history: Every Markdown file should be committed; history logs can be gitignored since they exist for local debugging only.

In the next article, we set up the full integration between Spec Kit and Claude Code for the Santekno Shop project — showing how the two work together to produce the best possible output.