github / github/spec-kit

Spec-kit commands consume significant portion of context window in every session

Abierto
#1,401 6 comentarios 15 reacciones 0 asignados Ver en GitHub
Lenguaje dominante
Python
Estrellas
137k
Forks
12.3k
Merge medio
2 d 7 h
PR fusionados (30 d)
155

Descripción

### Problem

When spec-kit is initialized, slash commands are added to `.claude/commands/` (or other agent's equivalent locations).

If others work like Claude Code, these commands are loaded into the agent's context window for **every chat session**, regardless of whether spec-kit is being actively used.

This creates a significant "context tax" that reduces the available working space for actual development tasks.

### Context Window Consumption

Based on `/context` output in Claude Code, spec-kit commands consume approximately **18.6k tokens**:

| Command | Tokens |
|---------|--------|
| speckit.checklist | 4.2k |
| speckit.specify | 3.1k |
| speckit.implement | 3.1k |
| speckit.clarify | 2.8k |
| speckit.analyze | 1.8k |
| speckit.tasks | 1.5k |
| speckit.constitution | 1.2k |
| speckit.plan | 690 |
| speckit.taskstoissues | 218 |

### Impact Across Supported Platforms

The ~18.6k token consumption impacts others in this way:

| Platform | Context Window | spec-kit Consumption |
|-----------------------------------|-----------------|----------------------|
| Cursor (default chat) | ~20k tokens | ~93% |
| Windsurf (typical) | 32-100k tokens | ~19-58% |
| GitHub Copilot (standard) | 64k tokens | ~29% |
| GitHub Copilot (VS Code Insiders) | 128k tokens | ~14.5% |
| Codex CLI (OpenAI) | 192-272k tokens | ~7-10% |
| Claude Code | 200k tokens | ~9.3% |
| Cursor (max mode) | 200k tokens | ~9.3% |
| Amazon Q Developer CLI | 200k tokens | ~9.3% |
| Amp (Sourcegraph) | 200-432k tokens | ~4-9% |
| Gemini CLI | 1M tokens | ~1.9% |
| Roo Code | model-dependent | varies |

The impact is most severe on:
- **Cursor default chat (~20k)**: spec-kit would consume nearly the entire context
- **GitHub Copilot standard (64k)**: nearly a third of available context
- **Windsurf**: varies by model, but often significant

### Why This Matters

Context window space is a finite and valuable resource. Every token consumed by spec-kit commands is a token unavailable for:

- **Code context**: Less room for file contents, reducing the agent's ability to understand the codebase
- **Conversation history**: Earlier parts of the conversation get truncated sooner
- **Agent reasoning**: Less space for the agent to think through complex problems

Users who have spec-kit installed but aren't actively using it for a particular task are paying this cost with no benefit.

### Possible Mitigation

One simple option might be `specify disable` / `specify enable` commands that move command files to/from a backup location (e.g., `.claude/commands-disabled/`), allowing users to toggle spec-kit out of context when not in use.

However, I imagine there may be better architectural solutions the maintainers could consider.

### My Environment

- Claude Code with Max plan (200k context)

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.