[Feature]: Prompt Style Guide
- Ngôn ngữ chính
- Python
- Star
- 137k
- Fork
- 12.3k
- Merge trung bình
- 2 ngày 12 giờ
- Pull request đã merge (30 ngày)
- 159
Mô tả
### 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.*
Hướng dẫn đóng góp
Hướng nghiên cứu
Bắt đầu bằng việc xem lại các phần được trích dẫn của templates/commands/specify.md và so sánh bố cục của các prompt template khác được nêu trong issue. Kiểm kê các mẫu prompt hiện có trước khi xác định hướng dẫn cơ sở và nhận diện các template cần được căn chỉnh. Công việc được xem là hoàn tất khi một tệp tài liệu Markdown ghi lại các quy tắc đã thống nhất và các prompt template hiện có đã được refactor nhẹ để phù hợp với chúng.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- markdown
- Lĩnh vực
- documentation
- Loại issue
- Tính năng
- Độ khó
- 4/5
- Thời gian dự kiến
- 3-5 ngày
- Mức độ hoạt động
- Sôi nổi
- Độ rõ ràng
- Khá rõ ràng
- Mức phù hợp với người mới
- 55/100