# Specsmaxxing--关于克服AI心理障碍，以及我为何用YAML编写规格说明

- 来源：Hacker News 热门（buzzing.cc 中文翻译）
- 作者：brendanmc6
- 发布时间：2026-05-03 17:37
- AIHOT 分数：65
- AIHOT 链接：https://aihot.virxact.com/items/cmoplafix0xb8sll99x71x2it
- 原文链接：https://acai.sh/blog/specsmaxxing

## AI 摘要

作者提出“Specsmaxxing”概念，旨在通过优化规格说明来克服AI心理障碍，即AI因指令模糊而产生的不可预测输出。其核心解决方案是采用YAML格式编写详细、结构化的规格说明，这能显著提升AI响应的准确性和一致性。为此，作者开源了一套配套工具包，供开发者实践此方法。该文章在Hacker News上获得了104点热度。

## 正文

​Does this look familiar?

You’re absolutely right! Let me fix that.

You’re absolutely right! Let me fix that.

You’re absolutely right! Let me fix that.

…

​Peak Slop

​Specifying the plane while we fly it

README.md

AGENTS.md

testing-guide.md

architecture.md

PRD.md

md.md

.md

.md

​Dreaming in markdown

​Acceptance Criteria for AI (ACAI)

# Requirements AUTH-1: Accepts `Authorization: Bearer ` header AUTH-2: Tokens are user-scoped, providing access to any of the user's resources AUTH-3: Rejects with 401 Unauthorized

# Requirements AUTH-1: Accepts `Authorization: Bearer ` header AUTH-2: Tokens are user-scoped, providing access to any of the user's resources AUTH-3: Rejects with 401 Unauthorized

// AUTH-1 const authHeader = req.headers["authorization"]; // AUTH-2 const isAuthorized = verifyBearerToken(authHeader); // AUTH-3 if (!isValid) return res.status(401).json({ error: "Unauthorized" });

// AUTH-1 const authHeader = req.headers["authorization"]; // AUTH-2 const isAuthorized = verifyBearerToken(authHeader); // AUTH-3 if (!isValid) return res.status(401).json({ error: "Unauthorized" });

Perhaps these tags can help me navigate these massive PRs?

Perhaps they can point me to where, exactly, a requirement is satisfied or tested!

Perhaps I can annotate them with notes and states (todo, assigned, completed)!

Perhaps I can start tracking acceptance coverage instead of test coverage!

Can my ACIDs number and label themselves?

Is it cumbersome to keep them aligned?

How do I share specs and progress across sandboxes, branches, features and implementations?

​Acai.sh - an open-source toolkit

A simple and flexible template for feature specs, called feature.yaml. Feature.yaml makes it possible to reference each requirement by ACID.

feature.yaml

Tiny CLI to power your CI and your agent (available on npm or via github release).

Webapp that serves a dashboard, and a JSON REST API (Elixir, Phoenix, Postgres).

​How it works

​Step 1 - Specify

feature.yaml

feature: name: imaginary-api-endpoint product: api description: This is an example feature spec for an imaginary REST API endpoint, using the feature.yaml format components: AUTH: name: Authn and Authz requirements: 1: Accepts Authorization header with `Bearer ` 1-1: Token must be non-expired, non-revoked 2: Respects the scopes configured for the owner 2-note: See `access-tokens.SCOPES.1` for complete list of supported scopes constraints: ENG: description: Constraints are for cross-cutting or under-the-hood requirements. Here are some example engineering constraints; requirements: 1: All actions are idempotent 2: All HTTP 2xx JSON responses wrap their payload in a root `data` key

feature: name: imaginary-api-endpoint product: api description: This is an example feature spec for an imaginary REST API endpoint, using the feature.yaml format components: AUTH: name: Authn and Authz requirements: 1: Accepts Authorization header with `Bearer ` 1-1: Token must be non-expired, non-revoked 2: Respects the scopes configured for the owner 2-note: See `access-tokens.SCOPES.1` for complete list of supported scopes constraints: ENG: description: Constraints are for cross-cutting or under-the-hood requirements. Here are some example engineering constraints; requirements: 1: All actions are idempotent 2: All HTTP 2xx JSON responses wrap their payload in a root `data` key

my-feature.ENG.2

​Step 2 - Ship

​Step 3 - Review

acai push

Create a free Team and Access Token at https://app.acai.sh

Expose the environment variable # .env ACAI_API_TOKEN=

# .env ACAI_API_TOKEN=

# .env ACAI_API_TOKEN=

Push specs and code refs to the dashboard for review acai push --all

acai push --all

acai push --all

​Step 4 - Iterate / repeat

acai

plan → implement → review

​Future Gazing

​Thought Experiment

feature.yaml

​-> From Specsmaxxing to Testmaxxing

​-> From Testmaxxing to reactive software factories

​Comparison to other spec-driven development tools

​GitHub SpecKit

​OpenSpec

​Kiro

​Traycer.ai

​Reasons you might not like acai.sh

You might not need to write specs. If your product is low-stakes, or simple, just keep prompting.

Acai specs are opinionated. You should write 1 spec per feature (though the feature boundary or slice is up to you). My opinion is that cross-cutting feature specs are easier to iterate, and really shine when a feature touches many codebases (frontend / backend / microservice etc.) and has many implementations (Production, Staging, Fix, etc.)

ACIDs rely on stable numbering. This creates zero friction when drafting a new spec, but requires care when revising a spec: you must re-align the code whenever your spec changes (almost forgot that this is the whole point?). The feature.yaml syntax supports deprecated and replaced_by flags as well, if you want to maintain a complete spec history inline.

deprecated

replaced_by

Acai discourages you from putting design and superficial requirements in your specs. Specs are for behavior, and constraints, and nothing else. I’ve learned from experience: get it working to-spec first, then do the superficial nail polish last 💅🏼.

Acai requires you to adopt the feature.yaml format. Almost zero learning curve. I have written an introductory guide to writing them. I recommend reading that first. Use npx @acai.sh/cli skill to teach your agent how. I also wrote a spec-for-the-spec if you want to go deeper.

npx @acai.sh/cli skill

​Hate it?