Add spec-authoring guide for AI-generated services#678
Merged
Conversation
Adds docs/docfx_project/articles/writing-specs.md, a guide for turning a business idea into a framework-aligned specification that an AI can implement predictably. It is the step before the AI code-generation article: it captures the conventions that keep a generated spec agreeing with framework defaults (422 for business/input validation and invalid state transitions vs 400 for protocol errors, value objects over primitives, stage-only repositories with a per-command unit of work, explicit HTTP/idempotency/ETag/pagination semantics, authorization, and real test coverage), plus a spec skeleton and a consistency checklist. Registered in the articles TOC under AI and Automation.
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new DocFX article that guides writing Trellis-aligned specifications intended for AI-assisted service generation, and links it into the documentation navigation under AI & Automation.
Changes:
- Added
writing-specs.mdarticle covering spec structure, value objects, status-code conventions, persistence/UoW, HTTP semantics, authorization, and testing expectations. - Registered the new article in
docs/docfx_project/articles/toc.ymlimmediately before the existing AI code generation article.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| docs/docfx_project/articles/writing-specs.md | New spec-authoring guide article intended to be handed to AI before code generation. |
| docs/docfx_project/articles/toc.yml | Adds the new article to the AI & Automation section of the docs TOC. |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #678 +/- ##
=======================================
Coverage 87.58% 87.59%
=======================================
Files 402 402
Lines 17525 17525
Branches 3673 3673
=======================================
+ Hits 15350 15351 +1
Misses 1332 1332
+ Partials 843 842 -1 🚀 New features to boost your workflow:
|
The idempotency reference documented the 400/409/422 status codes but not their source. Adds a note tracing them to draft-ietf-httpapi-idempotency-key-header section 2.7 (Error Handling): missing key -> 400, reuse with a different payload -> 422, in-flight retry -> 409; a malformed key stays 400 as a request-syntax error.
- Add the repo-required UTF-8 BOM so the file matches .editorconfig (charset = utf-8-bom) like the other DocFX articles. - Add the markdown separator rows to the Endpoints and Error Behavior tables in the copy/paste skeleton so it renders as tables when pasted. - Add trellis-api-primitives.md and trellis-value-object-taxonomy.md to related_api_reference (the article links to both).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a new documentation article,
docs/docfx_project/articles/writing-specs.md, registered in the articles TOC under AI & Automation (immediately before Trellis for AI Code Generation).Why
A precise, framework-aligned specification is the highest-leverage input to AI-assisted development. When a spec agrees with the framework defaults, generated code is predictable and review is fast; when it does not, every ambiguity is a place where runs and models diverge. This guide is meant to be handed to an AI (alongside a business plan) so it authors a spec that maps cleanly onto Trellis constructs -- the step before the existing AI code-generation article.
What it covers
RequiredEnum,ActorIdowners.Error.InvalidInput/Error.InvariantViolation); 400 limited to protocol errors (missing api-version, malformed JSON, missing/malformedIdempotency-Key).Docs-only. All internal links resolve;
audit-stale-docs.ps1passes; content verified against framework source and the existingerror-handling.md/ai-code-generation.mdarticles.