# nano-spec

**Repository Path**: ElecTest/nano-spec

## Basic Information

- **Project Name**: nano-spec
- **Description**: 规范驱动思维，纳米级文档
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-24
- **Last Updated**: 2025-12-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 规范驱动思维

## README

# Nano Spec

中文版 | [English](./README.md)

[![Stars](https://img.shields.io/github/stars/tao-hpu/nano-spec?style=social)](https://github.com/tao-hpu/nano-spec)
[![Forks](https://img.shields.io/github/forks/tao-hpu/nano-spec?style=social)](https://github.com/tao-hpu/nano-spec/fork)
[![Issues](https://img.shields.io/github/issues/tao-hpu/nano-spec)](https://github.com/tao-hpu/nano-spec/issues)
[![License](https://img.shields.io/github/license/tao-hpu/nano-spec)](./LICENSE)

> 规范驱动思维，纳米级文档。

一个轻量级的任务规范方法论，专为 AI 辅助开发设计。灵感来自 [Kiro 的规范驱动开发](https://kiro.dev/docs/specs/)，但更简洁实用。

![Nano Spec 概览](./assets/banner-cn.jpeg)

## 问题背景

在 AI 辅助开发的时代，我们面临一个文档困境：

```
无文档                    ???                 重文档
  |                        |                    |
  v                        v                    v
"直接写代码"            甜点区             PRD + 设计文档
快但混乱              nano-spec           + 技术方案 + ...
范围蔓延              4 个小文档            完整但慢
难以交接              思路清晰            写文档 > 写代码
```

**大多数任务都在中间地带** —— 太复杂不能"直接开干"，又没复杂到需要企业级规范。

## 为什么选择 nano-spec？

现代 AI 编程助手（Claude Code、Cursor、Copilot 等）功能强大，但当你清楚自己想要什么时，它们才能发挥最大作用。没有清晰的规范：

- AI 生成的代码可能偏离目标
- 你花在纠正上的时间比写代码还多
- 因为从未定义边界，范围不断蔓延
- 交接变成痛苦的知识转移

**nano-spec** 是"无文档"和"文档过载"之间的甜点区：

- **4 个文档，约 10 分钟搭建**
- **强制在编码前理清思路**
- **AI 友好的结构** —— AI 助手容易理解和遵循
- **人类也友好** —— 适合团队交接和未来的自己

| 方式 | 文档数 | 开销 | 适用场景 |
|:---|:---:|:---:|:---|
| 无规范 | 0 | 无 | 简单任务 |
| **nano-spec** | 4 | 低 | 大多数任务 |
| Kiro SPEC | 3+ | 高 | 复杂功能 |

## 4 个核心文档

```
tasks/{任务名}/
├── README.md   # 上下文：做什么 & 为什么
├── todo.md     # 计划：任务清单 & 验收标准
├── doc.md      # 产出：决策 & 结论
└── log.md      # 历程：每日进度 & 心得
```

| 文档 | 用途 | 何时编写 |
|:---|:---|:---|
| README.md | 背景、目标、范围、依赖 | 开始时 |
| todo.md | 任务清单 + 验收标准 | 开始时，持续更新 |
| doc.md | 技术决策、模式、图表 | 过程中 & 完成后 |
| log.md | 每日记录、阻塞点、发现 | 每天 |

## 核心原则

1. **边界优先** - 编码前先定义什么在范围内、什么在范围外
2. **验收标准** - 明确何时算完成
3. **决策留痕** - 未来的你会感谢现在的你
4. **进度留痕** - 记录过程，不只是结果

## 安装配置

### Claude Code

```bash
# 用户级别（所有项目可用）
mkdir -p ~/.claude/commands/
cp .claude/commands/nano-spec.md ~/.claude/commands/

# 或项目级别（仅当前项目）
mkdir -p /your-project/.claude/commands/
cp .claude/commands/nano-spec.md /your-project/.claude/commands/
```

> **说明**：只需要命令文件即可。当你运行 `/nano-spec create` 时，Claude 会根据你的描述自动生成 4 个文档，不需要 template 文件夹。

### Codex CLI

```bash
mkdir -p /your-project/.codex/
cp .codex/AGENTS.md /your-project/.codex/
```

### Gemini CLI

```bash
# 复制到项目根目录（Gemini CLI 会分层读取 GEMINI.md）
cp .gemini/GEMINI.md /your-project/GEMINI.md

# 或保留在 .gemini 文件夹
cp -r .gemini/ /your-project/

# 也可以在 ~/.gemini/GEMINI.md 设置全局指令
```

### Cline (VS Code 扩展)

```bash
# 单文件格式（简单）
cp .clinerules /your-project/

# 或目录格式（适合多个规则文件）
mkdir -p /your-project/.clinerules/
cp .clinerules /your-project/.clinerules/nano-spec.md
```

### Cursor

```bash
# 新格式（推荐，带 frontmatter 的 .mdc 文件）
mkdir -p /your-project/.cursor/rules/
cp .cursor/rules/nano-spec.mdc /your-project/.cursor/rules/

# 旧格式（仍可用，但即将废弃）
cp .cursorrules /your-project/
```

> **说明**：Cursor 正在从 `.cursorrules` 过渡到新的 `.cursor/rules/*.mdc` 格式。新格式支持 `description`、`globs`、`alwaysApply` 等元数据，规则管理更灵活。

### Windsurf

```bash
# 复制到项目根目录
cp .windsurfrules /your-project/
```

### Trae

```bash
# 复制到项目根目录（Trae 读取 .trae/rules/）
cp -r .trae/ /your-project/
```

### GitHub Copilot

```bash
# 复制到项目根目录
cp -r .github/ /your-project/
```

## 快速开始

### 手动设置

```bash
# 克隆模板
git clone https://github.com/tao-hpu/nano-spec.git
cd nano-spec

# 创建新任务
cp -r template/ tasks/my-new-task/
```

### 使用 Claude Code

```bash
# 使用内置的斜杠命令
/nano-spec create my-new-task "任务的简要描述"
```

### 使用 Codex CLI

```bash
codex "Create a nano-spec for: 我的任务描述"
```

### 使用 Gemini CLI

```bash
# 一次性提示
gemini -p "Create a nano-spec for: 我的任务描述"

# 或交互模式
gemini -i "Create a nano-spec for: 我的任务描述"
```

### 使用 Cline

在 VS Code 中安装 Cline 扩展后，直接输入：
```
Create a nano-spec for: 我的任务描述
```

### 使用 Cursor / Windsurf / Trae / GitHub Copilot

在这些编辑器的聊天中输入：
```
Create a nano-spec for: 我的任务描述
```

## 工具支持

| 工具 | 配置位置 | 状态 |
|:---|:---|:---:|
| Claude Code | `.claude/commands/nano-spec.md` | 已就绪 |
| OpenAI Codex | `.codex/AGENTS.md` | 已就绪 |
| Gemini CLI | `GEMINI.md` 或 `.gemini/GEMINI.md` | 已就绪 |
| Cline | `.clinerules` 或 `.clinerules/*.md` | 已就绪 |
| Cursor | `.cursor/rules/nano-spec.mdc` | 已就绪 |
| Windsurf | `.windsurfrules` | 已就绪 |
| Trae | `.trae/rules/project_rules.md` | 已就绪 |
| GitHub Copilot | `.github/copilot-instructions.md` | 已就绪 |

### 两类集成方式

**有原生命令系统的 CLI 工具**（Claude Code、Codex CLI、Gemini CLI）：
- 内置命令/代理/技能系统
- 配置文件定义结构化命令，可直接调用（如 `/nano-spec create`）
- 更强大：可定义参数、动作和工作流

**模型 API 之上的 IDE 封装**（Cursor、Windsurf、Cline、Trae、Copilot）：
- 本质是模型 API 之上的 UI 层
- 配置文件作为系统提示词注入，引导 AI 行为
- 只能用自然语言调用：`Create a nano-spec for: 我的任务`

两种方式都能很好地工作 - 区别只在于调用方式，产出质量没有差异。

## 模板结构

每个文档模板都设计得简洁而完整：

### README.md（上下文）
- 背景：这个任务为什么存在？
- 目标：我们要达成什么？
- 范围：什么在范围内、什么在范围外？
- 依赖：开始前需要什么？

### todo.md（计划）
- 调研：首先需要了解什么？
- 实施：分步骤的任务清单
- 验证：如何确认成功？
- 验收标准：必须完成 vs 锦上添花

### doc.md（产出）
- 摘要：一段话总结成果
- 关键决策：考虑过的方案及理由
- 技术细节：架构、模式、接口
- 待解决问题：尚未解决的问题

### log.md（历程）
- 每日记录：已完成、进行中、阻塞、备注
- 记录发现和心得
- 便于交接和复盘

## 工作流程与命令

### 第一步：创建规范（编码前）

| 工具 | 命令 |
|:---|:---|
| Claude Code | `/nano-spec create auth-feature "OAuth2 用户认证功能"` |
| Codex CLI | `codex "Create a nano-spec for: OAuth2 用户认证功能"` |
| Gemini CLI | `gemini -p "Create a nano-spec for: OAuth2 用户认证功能"` |
| Cline / Cursor / Windsurf / Trae / Copilot | `Create a nano-spec for: OAuth2 用户认证功能` |
| 手动 | `cp -r template/ tasks/auth-feature/` 然后编辑文件 |

### 第二步：开发过程中

让 AI 助手保持同步，随时更新文档：

```
# 查看当前进度
"读一下 todo.md，告诉我还剩什么没做"

# 记录今日工作
"在 log.md 添加：实现了 OAuth2 回调，token 刷新还有问题"

# 记录决策
"在 doc.md 记录：选择 JWT 而不是 session，因为..."

# 更新任务状态
"把 todo.md 里的'实现登录接口'标记为完成"
```

### 第三步：交接或评审

分享 4 个文件即可提供完整上下文：

```
# 快速了解状态
"根据 log.md 和 todo.md 总结一下当前进度"

# 新人上手
"读一下 tasks/auth-feature/ 的 4 个文件，解释一下这个项目"

# 范围确认
"有人问能不能加功能 X，看看 README.md 里是否在范围内？"
```

### 常用提示词速查

**Claude Code 斜杠命令：**
| 场景 | 命令 |
|:---|:---|
| 新建任务 | `/nano-spec create my-task "任务描述"` |
| 查看进度 | `/nano-spec status my-task` |
| 更新规范 | `/nano-spec update my-task "要更新的内容"` |

**自然语言（所有工具通用）：**
| 场景 | 提示词 |
|:---|:---|
| 更新任务 | `把 todo.md 里的 [任务] 标记为完成` |
| 记录决策 | `在 doc.md 记录：我们选择 X 而不是 Y，因为...` |
| 每日日志 | `在 log.md 添加今天的记录：[做了什么]` |
| 范围问题 | `[功能] 在这个任务的范围内吗？` |
| 交接说明 | `给新同事总结一下 tasks/[名称]/` |

## 示例

查看 [examples/notification-service/](./examples/notification-service/) 了解真实案例，演示通知服务的实现。

## 设计理念

> "即使有 AI，也要先想清楚再写代码。"

文档不是目的，**清晰才是。**

nano-spec 是一个思考框架，只是顺便产出了文档。它帮助你：

- **避免范围蔓延** - 提前定义边界
- **跟踪进度** - 无需复杂的项目管理工具
- **记录决策** - 留给未来参考
- **便于交接** - 清晰的上下文和历史

## 贡献

欢迎 PR，保持精简。

- Bug 报告和功能请求：[GitHub Issues](https://github.com/tao-hpu/nano-spec/issues)
- 欢迎改进模板或文档

## 许可证

MIT