github / github/spec-kit

[Feature]: Prompt Style Guide

Offen
#2,804 6 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
enhancement feature-assess feature-needs-clarification
Vorherrschende Sprache
Python
Sterne
137k
Forks
12.3k
Ø Merge
2 T. 12 Std.
Gemergte PRs (30 T.)
159

Beschreibung

### Problem Statement

I'm frustrated when I audit the core markdown prompt files and notice minor formatting, architectural, and structural consistency drift between sequential sections.

For example, in [templates/commands/specify.md (Lines 61-77)](https://github.com/github/spec-kit/blob/ed10b32014431a15c4e54e4ed7c92452230dd193/templates/commands/specify.md#L61-L77), Step 1 ("Generate a concise short name") uses clean dashes (`-`) to list out its sub-rules, but Step 2 ("Branch creation") drops bullet points entirely to use double-spaced paragraphs.

Additionally, within [templates/commands/specify.md (Lines 130-132)](https://github.com/github/spec-kit/blob/ed10b32014431a15c4e54e4ed7c92452230dd193/templates/commands/specify.md#L130-L132) under the Step 6 execution flow, section `v. Generate Functional Requirements` asks for "testable" requirements but does not explicitly mandate that they be "atomic."

Industry best practice for AI-driven software engineering shows that compound requirements can cause downstream logic fragmentation. While I haven't run into a broken output file myself, leaving these prompt discrepancies unaddressed introduces a strong hypothetical risk. An LLM might experience few-shot mimicry (structural anchoring), causing it to mirror the messy layouts or miss nested logic blocks entirely.

### Proposed Solution

I would like us to introduce a minimal Prompt Style Guide to establish baseline rules for any prompts added to this project (including core templates, community presets, and agent flows).

This guide will enforce:
1. Standardizing sub-step and constraint hierarchies using unified dashes (`-`).
2. Mandating explicit atomicity constraints for any prompt block generating requirements or tasks.
3. Prioritizing the active, imperative voice.

I plan to create this style guide by extracting the most common layout styles already present across the existing prompts. Any edge cases or styling ties during this baseline evaluation will be handled on a case-by-case basis.

### Alternatives Considered

I have considered several local and architectural workarounds, though none permanently solves the upstream problem for the community:
1. Using a local `.specify/memory/constitution.md` file to force these constraints at runtime.
2. Maintaining local template overrides inside individual project repositories.
3. Directly modifying the local `skill.md` files (which means effectively altering the underlying source code of Spec Kit).
4. Modifying agent-specific config files like `agents.md`.
5. Manually re-typing or editing the requirements into atomic, standard lines every single time the skill runs (highly inefficient).

### Component

Spec templates (BDD, Testing Strategy, etc.)

### AI Agent (if applicable)

None

### Use Cases

1. When community developers build new presets or commands, they have a clear guideline to prevent prompt quality from drifting.
2. During template maintenance, reviewers can instantly check incoming PRs against a set formatting baseline.
3. When AI agents run the workflows, consistent prompts help them follow the rules better and generate clean, atomic files.

### Acceptance Criteria

- [ ] A baseline Prompt Style Guide markdown file is added to the documentation.
- [ ] Existing prompt templates are lightly refactored to align with the new layout standard.

### Additional Context

I noticed these template consistency errors while auditing my local project setup.

*AI Disclosure: I used an AI assistant to help me write, refine, and format this entire issue template.*

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Start by reviewing the cited sections of templates/commands/specify.md and comparing the layout of the other prompt templates named in the issue. Inventory the existing prompt patterns before defining the baseline guide and identifying the templates that need alignment. Done means a documentation markdown file records the agreed rules and the existing prompt templates are lightly refactored to match them.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
markdown
Bereich
documentation
Issue-Typ
Feature
Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Aktivitätsstatus
Aktiv
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
55/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.