Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

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

オープン
  • 何か問題がありますか？
#2,139 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 2 日以内に返信

まだ誰も着手していません。

評価

難易度
3/5
見積もり時間
1〜2日
初心者へのやさしさ
45/100
issue の種類
ドキュメント
明瞭さ
おおむね明確
活発さ
活発
技術スタック
typescript
領域
documentation

調査の方向性

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.

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

説明

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.

主要言語
TypeScript
スター
73k
フォーク
5k
平均マージ
2日 9時間
マージ済み PR（30日）
71

環境構築

Codespaces で開く

このプロジェクトの開発コンテナを、あなたの GitHub アカウントでブラウザ上に起動します。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

Fission-AI/OpenSpec のほかの issue

Fission-AI/OpenSpec の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

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

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