English | 中文版
Spec-driven thinking, nano-sized docs.
A lightweight task specification methodology for AI-assisted development. Inspired by Kiro's Spec-Driven Development, but minimal and practical.
In the age of AI-assisted development, we face a documentation dilemma:
No Documentation ??? Heavy Documentation
| | |
v v v
"Just code it" Sweet Spot PRD + Design Doc
Fast but messy nano-spec + Tech Spec + ...
Scope creep 4 tiny docs Complete but slow
Hard to handoff Clear thinking Docs > Code time
Most tasks live in the middle — too complex for "just do it", too simple for enterprise-grade specs.
Modern AI coding assistants (Claude Code, Cursor, Copilot, etc.) are powerful, but they work better when you know what you want. Without clear specs:
- AI generates code that misses the point
- You spend more time correcting than coding
- Scope creeps because boundaries were never defined
- Handoffs become painful knowledge transfers
nano-spec is the sweet spot between "no documentation" and "documentation overhead":
- 4 documents, ~10 minutes to set up
- Forces clarity before coding
- AI-friendly structure — easy for AI assistants to understand and follow
- Human-friendly too — great for team handoffs and future you
| Approach | Docs | Overhead | Best For |
|---|---|---|---|
| No spec | 0 | None | Trivial tasks |
| nano-spec | 4 | Low | Most tasks |
| Kiro SPEC | 3+ | High | Complex features |
tasks/{task-name}/
├── README.md # Context: What & Why
├── todo.md # Plan: Tasks & Acceptance Criteria
├── doc.md # Output: Decisions & Conclusions
└── log.md # Journey: Daily progress & learnings
| Document | Purpose | When to Write |
|---|---|---|
| README.md | Background, goals, scope, dependencies | At start |
| todo.md | Checklist + acceptance criteria | At start, update as you go |
| doc.md | Technical decisions, schemas, diagrams | During & after |
| log.md | Daily notes, blockers, discoveries | Daily |
- Boundary first - Define what's in/out of scope before coding
- Acceptance criteria - Know when you're done
- Decisions documented - Future you will thank present you
- Progress logged - Track the journey, not just the destination
# User-level (available in all projects)
mkdir -p ~/.claude/skills/nano-spec/
cp .claude/skills/nano-spec/SKILL.md ~/.claude/skills/nano-spec/
# Or project-level (current project only)
mkdir -p /your-project/.claude/skills/nano-spec/
cp .claude/skills/nano-spec/SKILL.md /your-project/.claude/skills/nano-spec/Note: You only need the skill file. When you run
/nano-spec create, Claude will generate the 4 documents based on your description. No template folder required.New in Skills format: Claude can now understand natural language requests like "help me create a task spec for..." or "plan a new feature" and automatically invoke nano-spec.
mkdir -p /your-project/.codex/
cp .codex/AGENTS.md /your-project/.codex/# Copy to project root (Gemini CLI reads GEMINI.md hierarchically)
cp .gemini/GEMINI.md /your-project/GEMINI.md
# Or keep in .gemini folder
cp -r .gemini/ /your-project/
# You can also set global instructions at ~/.gemini/GEMINI.md# OpenCode reads AGENTS.md (same as Codex)
cp .codex/AGENTS.md /your-project/AGENTS.md
# Or keep in .codex folder
cp -r .codex/ /your-project/# Copy to .agent/rules/ (Antigravity project rules)
mkdir -p /your-project/.agent/rules/
cp .agent/rules/nano-spec.md /your-project/.agent/rules/
# Or use GEMINI.md (Antigravity also supports this)
cp .gemini/GEMINI.md /your-project/GEMINI.md# Single file format (simple)
cp .clinerules /your-project/
# Or directory format (for multiple rule files)
mkdir -p /your-project/.clinerules/
cp .clinerules /your-project/.clinerules/nano-spec.md# New format (recommended, .mdc with frontmatter)
mkdir -p /your-project/.cursor/rules/
cp .cursor/rules/nano-spec.mdc /your-project/.cursor/rules/
# Legacy format (still works, but will be deprecated)
cp .cursorrules /your-project/Note: Cursor is transitioning from
.cursorrulesto the new.cursor/rules/*.mdcformat. The new format supports metadata likedescription,globs, andalwaysApplyfor better rule management.
# Copy to project root
cp .windsurfrules /your-project/# Copy to project root (Trae reads .trae/rules/)
cp -r .trae/ /your-project/# Copy to project root
cp -r .github/ /your-project/# Clone the template
git clone https://github.com/tao-hpu/nano-spec.git
cd nano-spec
# Create a new task
cp -r template/ tasks/my-new-task/# Use the built-in slash command
/nano-spec create my-new-task "Brief description of the task"
# Or use natural language (Skills feature)
"Help me create a task spec for user authentication"
"I need to plan a new feature for notifications"codex "Create a nano-spec for: my task description"# One-off prompt
gemini -p "Create a nano-spec for: my task description"
# Or interactive mode
gemini -i "Create a nano-spec for: my task description"opencode "Create a nano-spec for: my task description"In Antigravity, just type in chat:
Create a nano-spec for: my task description
In VS Code with Cline extension, just type:
Create a nano-spec for: my task description
In any of these editors, just type in chat:
Create a nano-spec for: my task description
| Tool | Config Location | Status |
|---|---|---|
| Claude Code | .claude/skills/nano-spec/SKILL.md |
Ready |
| OpenAI Codex | .codex/AGENTS.md |
Ready |
| Gemini CLI | GEMINI.md or .gemini/GEMINI.md |
Ready |
| OpenCode | AGENTS.md or .codex/AGENTS.md |
Ready |
| Antigravity | .agent/rules/ or GEMINI.md |
Ready |
| Cline | .clinerules or .clinerules/*.md |
Ready |
| Cursor | .cursor/rules/nano-spec.mdc |
Ready |
| Windsurf | .windsurfrules |
Ready |
| Trae | .trae/rules/project_rules.md |
Ready |
| GitHub Copilot | .github/copilot-instructions.md |
Ready |
CLI tools with native skill/command systems (Claude Code, Codex CLI, Gemini CLI, OpenCode):
- Have built-in command/agent/skill systems
- Config files define structured commands that can be invoked directly (e.g.,
/nano-spec create) - More powerful: can define arguments, actions, and workflows
- Claude Code Skills bonus: Can also be triggered by natural language (e.g., "help me plan a task")
IDE wrappers over LLM APIs (Cursor, Windsurf, Cline, Trae, Copilot, Antigravity):
- Essentially UI layers on top of model APIs
- Config files are injected as system prompts to guide AI behavior
- Usage is natural language only:
Create a nano-spec for: my task
Both approaches work well — the difference is in how you invoke nano-spec, not in the output quality.
Each document template is designed to be minimal yet complete:
- Background: Why does this task exist?
- Goals: What are we trying to achieve?
- Scope: What's in and out of scope?
- Dependencies: What do we need before starting?
- Research: What do we need to learn first?
- Implementation: Step-by-step tasks
- Verification: How do we validate success?
- Acceptance Criteria: Must-have vs nice-to-have
- Summary: One-paragraph outcome
- Key Decisions: Options considered and rationale
- Technical Details: Architecture, schemas, interfaces
- Open Questions: Unresolved issues
- Daily entries: Done, In Progress, Blocked, Notes
- Captures discoveries and learnings
- Helps with handoffs and retrospectives
| Tool | Command |
|---|---|
| Claude Code | /nano-spec create auth-feature "User authentication with OAuth2" |
| Codex CLI | codex "Create a nano-spec for: user authentication with OAuth2" |
| Gemini CLI | gemini -p "Create a nano-spec for: user authentication with OAuth2" |
| OpenCode | opencode "Create a nano-spec for: user authentication with OAuth2" |
| Cline / Cursor / Windsurf / Trae / Copilot / Antigravity | Create a nano-spec for: user authentication with OAuth2 |
| Manual | cp -r template/ tasks/auth-feature/ then edit files |
Keep your AI assistant informed. Paste context or ask it to update docs:
# Check current progress
"Read my todo.md and tell me what's left"
# Log today's work
"Add to log.md: implemented OAuth2 callback, blocked on token refresh"
# Record a decision
"Add to doc.md: decided to use JWT instead of sessions because..."
# Update task status
"Mark 'implement login endpoint' as done in todo.md"
Share the 4 files for instant context:
# Quick status
"Summarize the current state from log.md and todo.md"
# Full context for new team member
"Read all 4 files in tasks/auth-feature/ and explain the project"
# Scope check
"Someone asked for feature X. Is it in scope per README.md?"
Claude Code slash commands:
| Scenario | Command |
|---|---|
| Create new task | /nano-spec create my-task "description" |
| Check progress | /nano-spec status my-task |
| Update spec | /nano-spec update my-task "what to change" |
Natural language (all tools):
| Scenario | Prompt |
|---|---|
| Update todo | Mark [task] as done in todo.md |
| Add decision | Document in doc.md: we chose X over Y because... |
| Daily log | Add today's entry to log.md: [what you did] |
| Scope question | Is [feature] in scope for this task? |
| Handoff | Summarize tasks/[name]/ for a new developer |
See examples/notification-service/ for a real-world example demonstrating a notification service implementation.
"Think before you code, even with AI."
The documents aren't the point. Clarity is.
nano-spec is a thinking framework that happens to produce documents. It helps you:
- Avoid scope creep by defining boundaries upfront
- Track progress without complex project management tools
- Document decisions for future reference
- Enable handoffs with clear context and history
PRs welcome. Keep it nano.
- Bug reports and feature requests: GitHub Issues
- Improvements to templates or documentation are always appreciated
MIT