Agent Skills
› NeverSight/learn-skills.dev
› spec-writing-rules
spec-writing-rules
GitHub强制全栈应用开发前的规范先行纪律，涵盖前后端、认证及数据库。要求生成包含架构、功能、非功能需求及可测试验收标准的完整规格说明书，确保代码编写前有明确契约。
Trigger Scenarios
需要编写前端或后端代码前
设计全栈Web应用架构时
定义API接口与数据模型时
Install
npx skills add NeverSight/learn-skills.dev --skill spec-writing-rules -g -y
SKILL.md
Frontmatter
{
"name": "spec-writing-rules",
"description": "Enforces clear, unambiguous, testable, FULL-STACK specification writing rules for Phase II web applications (Frontend + Backend + Auth + Database). Apply before any code is written.",
"allowed-tools": "Read, Write"
}
Full-Stack Specification Writing Rules (Phase II)
Purpose
This skill enforces a strict spec-before-code discipline for full-stack web applications.
No frontend, backend, database, or authentication code may be written until a complete, approved specification exists.
This specification acts as a binding contract between:
- Frontend (Next.js)
- Backend (FastAPI)
- Authentication (JWT / Better Auth)
- Database (SQLModel + PostgreSQL)
Core Principles
1. Specification-First Mandate
- NEVER write frontend or backend code before the specification is approved
- All APIs, UI flows, auth behavior, and data models must be defined first
- Specs must support multi-user, authenticated systems
- The specification is the single source of truth
Mandatory Specification Structure (Phase II)
Every Phase-2 spec MUST contain all sections below.
A. Overview
- Purpose: What problem does this system solve?
- Scope: What is included and explicitly excluded?
- Target Users: Authenticated users, roles (if any)
- System Architecture:
- Frontend (Next.js App Router)
- Backend (FastAPI)
- Auth (JWT via Better Auth)
- Database (Neon PostgreSQL)
B. Functional Requirements
1. Frontend Requirements
- Pages and routes (e.g.
/login,/tasks) - UI states (loading, empty, error)
- Auth flows (signup, signin, logout)
- API interaction behavior
- Client-side validation rules
2. Backend / API Requirements
For every endpoint, define:
- HTTP method + path
- Required headers (Authorization: Bearer JWT)
- Request body schema
- Response schema
- Success status codes
- Error status codes (401, 403, 404, 422, 500)
3. Authentication Requirements
- JWT issuance behavior
- Token expiry rules
- Unauthorized request handling
- User isolation rules (data ownership enforcement)
4. Data Requirements
- Entities and fields
- Field types and constraints
- Ownership rules (user_id)
- Indexing expectations
C. Non-Functional Requirements
- Security (JWT validation, user isolation)
- Performance expectations
- API consistency rules
- Error message clarity
- Environment variable usage (no hardcoded secrets)
D. Constraints
Technical Constraints
- Next.js App Router only
- FastAPI + SQLModel only
- PostgreSQL via Neon
- JWT authentication mandatory
Architectural Constraints
- Frontend NEVER directly accesses DB
- Backend NEVER trusts user_id from URL without JWT validation
- Stateless backend auth
E. Acceptance Criteria (CRITICAL)
Every feature must include:
- ✅ Happy-path scenario
- ❌ Unauthorized access scenario
- ❌ Cross-user access attempt
- ❌ Invalid payload scenario
- Edge cases (empty data, duplicates, limits)
Acceptance criteria must be directly testable by:
- API tests
- Manual UI testing
- Agent-based test-runner
Specification Lifecycle
Phase 1: Discovery
- Identify frontend + backend + auth needs
- Resolve ambiguity before writing spec
Phase 2: Drafting
- Write all mandatory sections
- Define contracts clearly between layers
Phase 3: Review
- User approval required
- No “TBD” allowed
Phase 4: Lock
- Mark spec as APPROVED
- Only then code generation may begin
Anti-Patterns (STRICTLY FORBIDDEN)
❌ Writing UI without API spec
❌ Writing API without auth rules
❌ Assuming frontend behavior
❌ Mixing implementation code in specs
❌ Skipping error cases
❌ Using vague language (“should”, “maybe”)
Quality Gate Checklist
Before approval, verify:
- Frontend + Backend + Auth covered
- Every API secured
- User data isolation defined
- JWT behavior specified
- Acceptance criteria are testable
- User explicitly approved spec
Usage
Invoke this skill when:
- Starting any Phase-2 feature
- Writing API, auth, or UI specifications
- Before generating backend or frontend code
- Preparing specs for agentic implementation
Success Criteria
A specification is complete when:
- Backend and frontend can be built independently
- No clarification is needed during coding
- Auth and security behavior is explicit
- Test-runner can validate it objectively
- User has approved it
Version History
- e0220ca Current 2026-07-05 23:37
