Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Spec guidance tells agents what to avoid, not how to keep a spec small and readable

Đang mở
  • Có gì không ổn?
#2,139 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 2 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
3/5
Thời gian dự kiến
1-2 ngày
Mức phù hợp với người mới
45/100
Loại issue
Tài liệu
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
typescript
Lĩnh vực
documentation

Hướng nghiên cứu

Start by reading the existing specs instruction and docs/writing-specs.md, then trace how openspec instructions specs --change <name> provides guidance to agents. Decide where positive guidance should live and how it should reach agents editing specs directly; the issue leaves both questions open. Done when the guidance helps agents write readable, focused requirements on every spec edit.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

Problem

Agents writing OpenSpec specs get format rules and a list of what to leave out. They get no picture of what a good spec looks like, and nothing says keeping it readable is their job. So each new behavior lands as another clause on the nearest requirement, and requirements keep growing until nobody reads them.

Who this affects

Anyone whose specs are mostly written and kept up by agents, especially long-lived projects. Every MODIFIED delta has to copy the whole requirement, so a grown requirement makes every later change to it large too.

What we've seen

In one of our own projects (about 800 requirements, all written by agents over a month):

  • 81% of the main spec's requirements have more than one SHALL. The longest has 19 SHALLs, and one runs to 791 words.
  • New requirements start out this way; they don't only grow into it. The share of newly added requirements with more than one SHALL went from 57% in late September to 90% in mid-October, and the average went from 1.8 to 5.0 SHALLs. The model was the same throughout. Agents copy the shape of the specs around them, so each long requirement makes the next one look normal.
  • A 10-word edit to one requirement produced a 180-word MODIFIED block.

Why today's guidance doesn't prevent it

  • The specs instruction covers what a spec is (a behavior contract), what to avoid, and the format (### Requirement: <name> followed by a description). It never says what a requirement is as a unit, who reads it, or how a spec as a whole should read.
  • docs/writing-specs.md has the right idea ("A good requirement is one behavior, stated so plainly you could hand it to someone else to test"), but agents never receive that doc.
  • Agents can only get the guidance through openspec instructions specs --change <name>. An agent editing openspec/specs/ directly, or editing a delta after it was written, gets none of it.
  • The fix so far has been rules: a 500-character limit, plus exceptions for when to split and when not to (#2069 asks to make the limit configurable). Each edge case adds another rule, and none of them tells the agent what it's aiming for.

What we have in mind (open for discussion)

Positive guidance that makes the agent the spec's keeper:

  • What a requirement is: one promise someone relies on, named after that promise, in a sentence or two. Its cases, failures included, are its scenarios.
  • Who reads it: a reviewer deciding yes or no, a test that names a scenario, the next agent changing it. So each requirement should stand on its own and be changeable on its own.
  • The spec as an outline: read top to bottom, the requirement headers should list what the capability promises.
  • Where new behavior goes: ask whether it's a new promise or a change to an existing one.
  • Leave it easier to read than you found it: that includes splitting a multi-promise requirement you're already editing.
  • Reachable on every edit: an agent should get this whenever it edits a spec, not only when it creates a change's specs artifact.

We're trying a version of this as a project rule and will report back on what changes.

Open questions:

  1. Should this live in the schema's specs instruction, in a shared spec-writing instruction any workflow can load, or both?
  2. Should splitting a requirement you're editing be the default? Today the guidance says to split only when the user asks.

Related: #2069, #829.

Ngôn ngữ chính
TypeScript
Star
73k
Fork
5k
Merge trung bình
2 ngày 7 giờ
Pull request đã merge (30 ngày)
67

Chuẩn bị môi trường

Mở trong Codespaces

Khởi chạy dev container của dự án ngay trên trình duyệt, bằng tài khoản GitHub của bạn.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của Fission-AI/OpenSpec

Tất cả issue của Fission-AI/OpenSpec

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.