Spec Design
Designspec-designSpec Design is an Agent Skill for design published in the MagicCube/agentara repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Guides interactive module design via Q&A before writing. Use when the user wants to design a module, class, or feature together, or when they say "/spec-design".
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/MagicCube/agentara/blob/HEAD/.claude/skills/spec-design/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/spec-design, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Spec Design
Guides a collaborative, question-first design process. Do not write design docs until ambiguities are clarified.
Process
Phase 1: Clarify First (Required)
Always start with clarifying questions. Do not propose a design or write a doc until the user answers.
Read relevant code (e.g. docs/overview.md, related src/ modules, config) to ground your questions. Then ask questions in categories below.
Phase 2: Question Categories
Ask 1–2 questions per category as needed. Adapt to context; not all apply.
| Category | Examples |
|---|---|
| Path / terminology | "You said directory—do you mean file? resolveX() returns a file path." |
| Data flow | "Where does X come from—caller, config, or generated internally?" |
| Responsibilities | "Is this a factory, a repository, or both? What does it own vs delegate?" |
| Semantics | "Does 'resume' mean load history into context, or just set a flag?" |
| Concurrency | "Same ID—allow multiple instances? Do we need caching?" |
| Error handling | "File missing on resume—throw or return Result? Overwrite on create?" |
| Injection | "Config via constructor injection or direct import?" |
If something contradicts existing code or docs, ask immediately.
Phase 3: Iterate
- Answer user answers; refine or add questions if needed
- Proceed to writing only when the design is clear enough to implement
Phase 4: Produce
- Write design doc to
docs/designs/{module-name}.md - Naming: Use kebab-case from class/module name (e.g.
SessionManager→session-manager.md) - Language: English only
- Style: Concise. No filler. Bullets and short sentences.
Output Format
Design doc structure (adjust as needed):
# {ModuleName} Design
One-line summary.
## Dependencies
- Imports, paths, config
## API
- Method signatures and behavior
## Error Handling
- When to throw, no graceful fallback
## Concurrency / Constraints
- Single-writer, no cache, etc.
Anti-Patterns
- Rushing to write: Asking questions and writing in the same turn
- Assuming: Filling gaps without asking (e.g. "目录" vs "文件")
- Over-specifying: Adding details the user did not confirm
- Chinese in design doc: Keep design docs in English