Getting Started with SEDAI

Learn SED methodology by manually creating specifications - CLI tools are optional

Understanding SED is More Important Than Using Tools

SED is a methodology for creating precise, complete specifications that AI can implement exactly. While SEDAI provides CLI tools for convenience, we strongly recommend manually creating your first specification structure to gain a deeper understanding of SED principles.

Recommended Approach: Follow the manual 7-step process below to truly understand how SED works. The CLI tools (npx spec init) are optional helpers that you can use later once you've mastered the methodology.

Create the specs directory

Start by creating the main directory that will contain all your specifications.

mkdir specs

Why this matters: Centralizing all specifications in a dedicated directory makes them easy for both AI and developers to find and reference.

Write index.md (Detailed Table of Contents)

Create the index file that serves as a navigation map for all your specifications.

Create specs/index.md with YAML header
Include project summary and overview
List all specification files with brief descriptions
This is the first file AI should read to understand your project structure

Why this matters: The index.md serves as a Detailed Table of Contents (DTOC), allowing AI to quickly understand the full scope and structure of your project before diving into specific specifications.

Configure AI Instructions Reference

Direct AI to read SED development instructions from the web.

Add the following directive to your `specs/index.md`:

Copy and paste this markdown snippet into your specs/index.md file to ensure AI reads SED instructions:

---
## 🔥 MUST-FOLLOW: SED (Spec-Exact Development) Instructions

All developers and AI must strictly follow SED guidelines:
📖 **Required**: Read and understand https://sedai.dev/instructions before starting any development work.
---

What this directive does:

Instructs AI to read https://sedai.dev/instructions before starting work
Ensures AI understands Index-Driven Development workflow rules
AI learns Dependency Resolution requirements from the web
AI understands Specification Obedience principles
No need to maintain a local instructions.md file

Why this matters: By referencing the canonical web version, AI always has access to the latest SED development instructions, ensuring adherence to SED principles throughout development.

Write individual specification files

Create detailed specification files for each component of your project as described in Spec Structure.

Follow the naming convention: <project>-<module>-<feature>.md
Include YAML headers with metadata (title, author, date, version, status, dependencies)
Structure each file with required sections:
- Overview: High-level summary of what this spec covers
- Requirements: Functional and non-functional requirements
- Workflow: User workflows and process flows
- Details: Technical implementation details
Specify everything: database schemas, API endpoints, function signatures, UI components, testing criteria, error handling, etc.

Optional Enhancements

The following features are optional and can enhance your specifications:

📋 Table of Contents (TOC)

Optionally add a Table of Contents at the top of your index.md to help developers and AI navigate through all specifications quickly.

🔗 External References

Optionally add internet URL references to external specifications and shared specs repositories, not just local specs folder files.

Why this matters: The completeness and precision of these specifications directly determine how accurately AI can implement your project. Vague specs lead to implementation errors. For comprehensive guidance on specification structure, YAML headers, dependencies, and best practices, refer to the Spec Structure documentation.

Request AI evaluation

Before starting development, ask AI to score your specifications to ensure they meet SED quality standards.

Evaluation Criteria (100 points):

Completeness (40 pts): Problem definition, inputs/outputs, constraints, acceptance criteria, dependencies, examples
Clarity (30 pts): Unambiguous language, consistent structure, visual aids, no contradictions
Adherence to SED Principles (30 pts): SED philosophy referenced, instructions aligned, risk/assumption disclosure

Use this evaluation prompt:

Read the following documents first to understand the concept of SED:
  - https://sedai.dev/
  - https://sedai.dev/what-is-sed
  - https://sedai.dev/principles
  - https://sedai.dev/philosophy

Then, please evaluate the specifications in the ./specs directory by referring to:
  - https://sedai.dev/instructions
  - https://sedai.dev/structure
  - https://sedai.dev/examples
  - https://sedai.dev/score

Build a rubric with 100 total points:
- Completeness (40 pts): Problem definition, inputs/outputs, constraints, dependencies, examples
- Clarity (30 pts): Unambiguous language, consistent structure, visual aids
- Adherence to SED Principles (30 pts): SED philosophy referenced, instructions aligned

For each spec file:
- Assign 0-100 score with subscores per dimension
- List Top 3 Gaps with actionable fixes
- Provide Readiness Level: Draft / Review-Ready / Build-Ready

Provide an overall project score (weighted average) and a prioritized backlog (5-10 items)
for spec improvements with target files and expected score uplift.

Why this matters: AI evaluation helps you identify gaps, ambiguities, and missing details in your specifications before implementation begins, saving time and reducing errors.

Using `/score` in AI Coding Assistants

Running npx sedai automatically installs the /score command for multiple AI coding assistants:

Claude Code: .claude/commands/score.md
GitHub Copilot: .github/copilot-instructions.md
Codex & Other AI Agents: AGENTS.md

You can evaluate your specifications with a simple slash command:

# Basic: Evaluate ./specs directory and output in markdown format
/score

# Evaluate a different directory
/score docs/specs

# Get results in JSON format
/score ./specs json

After all, it's just a prompt. SED is fundamentally about clear communication with AI—regardless of which AI you use.

You don't need to rely on npx sedai commands. SED works with any AI (Claude, ChatGPT, Gemini, etc.). Simply talk to your AI as you would naturally, asking it to score your specifications, provide feedback, and develop following the SED methodology. The essence of SED is the conversation, not the tools.

Begin development (only if score ≥ 95)

Only proceed with implementation when your specifications meet the quality threshold.

If the overall project score is 95 or higher, you can proceed with development
If below 95, improve your specifications based on AI recommendations
Re-evaluate after making improvements until achieving the minimum score threshold
Never compromise on specification quality - poor specs lead to poor implementation

Why this matters: The 95+ threshold ensures your specifications are complete enough for AI to implement correctly without guessing or making assumptions.

Configure AI System Prompts for SED Compliance

Add SED compliance rules to your AI's system prompt files to ensure consistent adherence throughout development.

Common System Prompt Files:

CLAUDE.md - For Claude AI
AGENTS.md - For AI agents
.github/copilot-instructions.md - For GitHub Copilot

Mandatory Requirements to Include:

Learn SED Methodology: Read the following pages and understand SED methodology:
Always Consult Specifications First: Before starting any development task, read https://sedai.dev/instructions and ./specs/index.md
Strict Specification Obedience:
- Follow specifications exactly, even if they appear incorrect
- Never implement features not defined in specifications
- Never modify specifications directly during implementation
- If specifications are unclear, ask for clarification rather than guessing
Error Reporting Protocol: When critical errors are detected in specifications:
- Halt development immediately
- Report the issue to developers with specific details
- Recommend specification improvements
- Wait for specification updates before continuing
Ask for Clarification When Needed: When specifications are ambiguous or incomplete:
- Request clarification from the developer instead of making assumptions
- Ask for specific details about logic, source code, styles, or any other information needed
- Never proceed with implementation based on guesswork or inference
- Ensure all details are explicitly documented before continuing development

Quick Copy Template:

Copy the following markdown template and paste it into your AI system prompt files:




# Workflow for Claude SED Agent

- [ ] Learn SED Methodology: Read the following pages and understand SED methodology:
  - https://sedai.dev
  - https://sedai.dev/principles
  - https://sedai.dev/philosophy

- [ ] Always Consult Specifications First: Before starting any development task, read https://sedai.dev/instructions and ./specs/index.md

- [ ] Strict Specification Obedience:
  - Follow specifications exactly, even if they appear incorrect
  - Never implement features not defined in specifications
  - Never modify specifications directly during implementation
  - If specifications are unclear, ask for clarification rather than guessing

- [ ] Error Reporting Protocol: When critical errors are detected in specifications:
  - Halt development immediately
  - Report the issue to developers with specific details
  - Recommend specification improvements
  - Wait for specification updates before continuing

- [ ] Ask for Clarification When Needed: When specifications are ambiguous or incomplete:
  - Request clarification from the developer instead of making assumptions
  - Ask for specific details about logic, source code, styles, or any other information needed
  - Never proceed with implementation based on guesswork or inference
  - Ensure all details are explicitly documented before continuing development

Why this matters: System prompts ensure AI consistently follows SED principles across all development sessions, preventing spec deviation and maintaining implementation accuracy.

Optional

Using CLI Tools

Important: The CLI tools are convenience features, not requirements. Understanding the manual process above is more important than using these tools. Use them only after you've created specifications manually at least once.

Installation

SEDAI can be installed globally or used directly with npx. Both sedai and spec commands are available.

Global Installation:

npm install -g sedai

Use with npx (No Installation):

npx spec --help

spec init - Project Scaffolding

Automatically generates the initial specification structure (equivalent to Steps 1-3 above).

Interactive Mode:

npx spec init

The tool will prompt you for project name, summary, author, and email.

Non-Interactive Mode:

npx spec init -n "my-app" -s "My project" -a "Your Name" -e "[email protected]"

All options provided via command-line flags.

Options:

-n, --name <name> - Project name
-s, --summary <summary> - Project summary/description
-a, --author <author> - Author name
-e, --email <email> - Author email

Generated Files:

specs/index.md - Main index specification
specs/<name>-setup-database.md - Database setup template
specs/<name>-setup-backend.md - Backend setup template
specs/<name>-setup-frontend.md - Frontend setup template

Other Commands (Coming Soon)

`spec doctor`

Validate all specification files in your project

`spec validate`

Validate a single specification file

`spec score`

Calculate completeness score (0-100) for a spec

Remember: Even if you use CLI tools to generate initial files, you must still manually fill in the detailed specifications (Step 4) and have AI evaluate them (Step 5) before development.

← Previous: Principles Next: Workflow →

SEDAI