github / github/spec-kit

[Feature]: Prompt Style Guide

オープン
#2,804 コメント 6 件 リアクション 0 件 担当者 0 名 GitHub で見る
enhancement feature-assess feature-needs-clarification
主要言語
Python
スター
137k
フォーク
12.3k
平均マージ
2日 12時間
マージ済み PR(30日)
159

説明

### 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.*

コントリビューションガイド

コントリビューションガイドを開く

調査の方向性

まず templates/commands/specify.md の引用されたセクションを確認し、issue で名前が挙げられている他のプロンプトテンプレートのレイアウトと比較します。ベースラインガイドを定義し、整合させる必要があるテンプレートを特定する前に、既存のプロンプトパターンを洗い出します。合意したルールを記録した Markdown ドキュメントファイルが作成され、既存のプロンプトテンプレートがそれに合わせて軽くリファクタリングされていれば完了です。

索引モデルが issue の本文から書いたものです。

評価

技術スタック
markdown
領域
documentation
issue の種類
機能追加
難易度
4/5
見積もり時間
3〜5日
活発さ
活発
明瞭さ
おおむね明確
初心者へのやさしさ
55/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。