Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#2,139 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 2 días

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
3/5
Tiempo estimado
1-2 días
Aptitud para principiantes
45/100
Tipo de issue
Documentación
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
typescript
Área
documentation

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
TypeScript
Estrellas
73k
Forks
5k
Merge medio
2 d 9 h
PR fusionados (30 d)
71

Preparar el entorno

Abrir en Codespaces

Inicia el contenedor de desarrollo del proyecto en tu navegador, con tu propia cuenta de GitHub.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de Fission-AI/OpenSpec

Todos los issues de Fission-AI/OpenSpec

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.