常见问题

快速开始

什么是 HarnSpec？

HarnSpec 是一个为 AI 辅助开发优化的轻量级 Spec 框架。它是一个 CLI 工具 + markdown 文件，位于您的仓库中，帮助您记录技术决策并指导 AI 编码工具，同时将 Spec 保持在约 2,000 Token 的最佳范围内。

关键功能：

用于轻松引用的编号 Spec
用于创建、搜索和管理 Spec 的 CLI 工具
用于 AI 工具集成的 Agent Skills（GitHub Copilot、Claude Code、Cursor 等）
验证以确保 Spec 质量
用于项目可见性的看板和统计

5 分钟设置：

npm install -g harnspec
cd your-project
harnspec init
harnspec create my-first-spec

无需配置文件，无需数据库，无需服务器。适用于任何编辑器和任何 AI 工具。

如何开始使用 HarnSpec？

这是最常见的问题！以下是您的快速入门路径：

方式 1：尝试教程项目（推荐新手使用）

npx harnspec init --example dark-theme
cd dark-theme && npm install && npm start

方式 2：添加到现有项目

npm install -g harnspec
cd your-project
harnspec init
harnspec create my-first-feature

设置完成后：

运行 harnspec board 查看看板视图
编辑您的 Spec 文件 specs/001-my-first-feature/README.md
开始编码时运行 harnspec update 001 --status in-progress
完成后运行 harnspec update 001 --status complete

下一步：

为什么使用 HarnSpec？

在以下情况下使用 HarnSpec：

需要团队在复杂功能上达成一致
需要设计决策的文档
需要上下文以减少 AI 幻觉
需要新团队成员的入职材料

对于以下情况跳过 HarnSpec：

简单的错误修复
一次性原型
具有明确需求的单人项目

哲学： 在最大敏捷性的同时获得 80% 的 vibe 编码速度和 80% 的结构化 Spec 优势。

HarnSpec 能加速我的开发吗？

可以，但需要理解其原理。 HarnSpec 不是让你打字更快——而是减少返工和提高 AI 输出质量。

如何加速开发：

更好的 AI 输出 - Spec 提供聚焦的上下文（<2,000 Token），AI 模型处理起来比分散的对话历史更准确
更少返工 - 预先明确需求 = 更少的"这不是我想要的"循环
更快上手 - 新团队成员（或 AI 助手）能立即理解决策
减少上下文腐化 - 当 AI 有书面 Spec 可参考时，不会产生幻觉

实际影响：

单次实现尝试更容易成功（而不是 3-4 次来回循环）
减少重复解释相同决策的时间
团队对齐只需一次，而不是每个 Sprint 都来一遍

什么时候 HarnSpec 可能拖慢你：

简单的 bug 修复（跳过 Spec，直接修）
一次性原型（vibe 编码更快）
非常清晰、明确的工作

公式： 节省的时间 = (避免的 AI 返工) + (避免的团队同步) - (Spec 编写时间)

对于复杂功能，这几乎总是正值。对于琐碎的更改，跳过 Spec。

为什么有 2,000 Token 目标？

注意力是稀缺资源，而不是存储。

三个原因：

人类注意力范围 - 人与 AI 搭档一次只能处理约 2-3K Token
AI 性能 - 上下文质量在 50K Token 硬上限之前就开始下降
工作记忆 (Working Memory) - Token 数量直接对应认知负荷，而行数受格式影响很大

如果您的 Spec 超过 3,500 Token，请将其拆分为子 Spec 文件（DESIGN.md、IMPLEMENTATION.md、TESTING.md 等）；超过 5,000 Token 必须立即拆分。详见第一原则。

框架对比

HarnSpec 与其他 SDD 框架有什么区别？

HarnSpec vs Spec Kit vs OpenSpec：

方面	HarnSpec	Spec Kit	OpenSpec
理念	轻量、灵活	结构化治理	正式提案
Spec 大小	<2,000 Token（优化）	较长上下文	较长系统提示
工作流	灵活，适应团队	需要 5 步流程	提案→评审→归档
模板	简约可定制	固定格式	固定 delta 格式
AI 集成	Agent Skills + CLI	Slash 命令	Slash 命令
可视化 UI	✅ 有	❌ 仅 CLI	❌ 仅 CLI
适合场景	追求敏捷的团队	企业治理	正式变更跟踪

HarnSpec 的关键优势：

上下文经济 (Context Economy) - 为 AI 工作记忆优化
编辑器无关 - 适用于任何 AI 工具（Copilot、Claude、Cursor 等）
低认知负荷 - 从简单开始，按需扩展
可视化模式 - Web UI 用于浏览和展示 Spec

何时选择其他框架：

Spec Kit：需要结构化 5 步治理的企业团队
OpenSpec：需要正式提案/评审工作流的团队
Kiro：想要集成 AI IDE 的团队（但有供应商锁定）

📖 详细对比分析 →

AI 集成

HarnSpec 只适用于 Claude 模型吗？

不！HarnSpec 适用于任何 AI 模型或编码助手。

HarnSpec 设计上与模型无关：

支持 Agent Skills 的工具（完整集成）：

GitHub Copilot (VS Code)
Claude Code / Claude Desktop
Cursor
Windsurf
Cline
Gemini CLI
还有更多...

任何 AI 工具（通过文件引用）：

读取 specs/042-my-feature/README.md 并相应实现。

为什么到处都能用：

Spec 只是仓库中的 markdown 文件
AI 像读取其他文档一样读取它们
Agent Skills 提供更丰富的方法论引导

2,000 Token 限制基于认知科学和 AI 注意力研究——它对所有模型都有帮助，不仅仅是 Claude。

如何将 HarnSpec 集成到 Claude Code？

快速设置（1 分钟）：

在项目目录运行：

harnspec skill install

这将安装 harnspec 技能，使 Claude Code 能够理解 SDD 方法论并自动使用 CLI 工具。

📖 完整 AI 集成指南 →

为什么我的 AI 代理不遵循 HarnSpec 工作流？

常见原因和解决方案：

1. 没有 AGENTS.md 文件

AI 代理需要明确的指令。在项目根目录创建 AGENTS.md：

harnspec init  # 自动创建 AGENTS.md

或从这里复制：AGENTS.md 模板

2. AGENTS.md 不在上下文中

AI 工具有不同的方式加载项目文件：

VS Code Copilot：添加 @workspace 以包含项目文件
Claude Code：通过 Agent Skills 自动加载 AGENTS.md
Cursor：使用 .cursorrules（将 AGENTS.md 内容复制到那里）

3. 指令太长

如果 AGENTS.md 太长，AI 可能会忽略部分内容。保持在 2,000 Token 以内。

4. 指令冲突

检查是否有其他可能冲突的指令文件：

.github/copilot-instructions.md
.cursorrules
系统提示或 AI 代理配置

5. AI 无法访问项目方法论

确保安装了 Agent Skills，使 AI 掌握 SDD 的最佳实践：

harnspec skill install

调试技巧： 直接询问 AI：

你有关于 HarnSpec 工作流的什么指令？
你能列出这个项目中的 Spec 吗？

📖 代理配置指南 →

使用 HarnSpec

如何升级或重新初始化 HarnSpec 而不丢失我的 Spec？

HarnSpec 内置了安全的重新初始化功能。 您不需要手动删除任何内容。

场景 1：升级到最新配置（最安全）

harnspec init -y

这会将您现有的配置与最新默认值合并。所有 Spec 和 AGENTS.md 都会保留。

场景 2：重置配置但保留 Spec

harnspec init -f

这会重置 .harnspec/ 配置，但保持您的 specs/ 目录完好无损。

场景 3：交互式选择

harnspec init

当 HarnSpec 已经初始化时，您会看到以下选项：

升级配置（推荐）- 更新配置，保留所有内容
重置配置 - 全新配置，保留 Spec
完全重置 - 从头开始（需要确认）
取消 - 退出不做任何更改

每个选项保留什么：

选项	`.harnspec/`	`specs/`	`AGENTS.md`
升级	合并	✅ 保留	✅ 保留
重置配置	全新	✅ 保留	重新创建
完全重置	删除	❌ 删除	❌ 删除

专业提示： 在 CI/CD 流水线中始终使用 -y——它默认使用最安全的升级选项。

如何查看 HarnSpec UI？

启动 Web UI：

harnspec ui

这会在 http://localhost:3000 打开浏览器，包含：

Spec 浏览器 - 浏览和搜索所有 Spec
看板视图 - Kanban 风格的可视化
依赖图 - Spec 之间的可视化关系
项目统计 - 包含指标的仪表板

替代方法（无需安装 CLI）：

npx @HarnSpec/ui

选项：

harnspec ui --port 3100    # 自定义端口
harnspec ui --no-open      # 不自动打开浏览器
harnspec ui --specs ./path # 自定义 Spec 目录

📖 可视化模式指南 →

如何使用 HarnSpec 管理多个功能开发？

HarnSpec 擅长管理并发开发：

1. 为每个功能创建 Spec：

harnspec create user-auth --tags auth,api --priority high
harnspec create payment-flow --tags payments,api --priority high
harnspec create dashboard --tags frontend,ui --priority medium

2. 跟踪关系：

# Dashboard 依赖于 auth 完成
harnspec link dashboard --depends-on user-auth

# Payment 和 auth 相关但独立
harnspec link payment-flow --related user-auth

3. 可视化进度：

harnspec board          # 看板视图
harnspec stats          # 项目指标
harnspec deps dashboard # 查看什么阻塞了 dashboard

4. 按状态或标签筛选：

harnspec list --status in-progress    # 正在进行什么？
harnspec list --tag api               # 所有 API 相关的 Spec
harnspec list --assignee @alice       # Alice 的工作

5. 使用 UI 提高团队可见性：

harnspec ui
# 在团队会议中分享 http://localhost:3000

管理多个功能的最佳实践：

一致使用标签（api、frontend、backend 等）
设置优先级（critical、high、medium、low）
严格更新状态（planned → in-progress → complete）
谨慎使用 depends_on（仅用于真正的阻塞项）
使用 related 作为信息性链接

如何处理已完成 Spec 中的 Bug？

已实现功能中的 Bug 需要根据严重程度不同处理：

选项 1：小 Bug（快速修复）

不需要创建新 Spec。直接修复：

# 简单 bug 修复不需要 Spec
git commit -m "fix: handle null user in auth flow (spec-042)"

在提交消息中引用原始 Spec 以便追溯。

选项 2：重大 Bug（设计缺陷）

创建后续 Spec：

harnspec create auth-token-refresh-fix --tags auth,bugfix --priority high

链接到原始 Spec：

harnspec link auth-token-refresh-fix --related user-auth

在新 Spec 中记录：

原始实现出了什么问题
根本原因分析
更新后的设计决策

选项 3：更新原始 Spec

如果 Bug 揭示了遗漏的需求：

harnspec open user-auth
# 添加"经验教训"部分记录问题
# 用修正后的方法更新相关部分

何时使用每个选项：

Bug 类型	操作
拼写错误、差一错误	直接修复（无需 Spec）
遗漏的边界情况	添加到原始 Spec
设计缺陷	新的后续 Spec
破坏性更改	带迁移计划的新 Spec

关键原则： Spec 记录决策，而不是代码。如果决策错误，更新 Spec。如果实现错误，直接修复代码。

故障排除

我的Spec被 AI 编辑损坏了

原因： Spec超过上下文窗口，AI 失去了结构跟踪。

修复：

git checkout HEAD -- specs/042-my-spec/  # 从 git 恢复
harnspec validate                        # 检查问题

预防： 将Spec控制在 2,000 Token 以内（3,500 Token警告，5,000 Token硬限制），并在编辑前运行 harnspec tokens <spec> 检查。

`harnspec update` 说"找不到Spec"

调试：

harnspec list          # 查看所有活动Spec
harnspec list --all    # 包括已归档

常见原因：

不在带有 specs/ 目录的 git 仓库中
Spec名称/编号拼写错误
Spec被归档

frontmatter验证失败

常见错误：

手动编辑系统管理的字段（status、created_at、transitions 等）
无效的 YAML 语法
字段名称拼写错误

修复：

harnspec validate      # 查看确切的错误

始终使用 CLI 命令更新元数据：

harnspec update 042 --status in-progress
harnspec update 042 --priority high
harnspec update 042 --tags api,backend

如何恢复已删除的Spec？

Spec只是 git 中的文件：

git log --all --full-history -- "specs/042-my-spec/*"
git checkout <commit> -- specs/042-my-spec/

或从已归档恢复：

mv archived/042-my-spec specs/
harnspec update 042 --status in-progress

CLI 命令不工作

检查安装：

which harnspec
harnspec --version

如果需要，重新安装：

npm install -g harnspec

验证您在 git 仓库中：

git rev-parse --git-dir

贡献与支持

如何报告错误或请求功能？

错误： GitHub Issues
功能： GitHub Discussions

我可以贡献吗？

可以！请参见 CONTRIBUTING.md。

常见贡献：

文档改进
错误修复
新模板
Agent Skills 增强

我可以在哪里获得帮助？

文档： 完整指南
讨论： GitHub Discussions
问题： 错误跟踪器
Twitter/X： @MarvinZhang89

许可证是什么？

MIT 许可证 - 可免费用于商业和个人用途。

更多问题？ 查看完整文档或在 GitHub Discussions 中提问。

快速开始​

什么是 HarnSpec？​

如何开始使用 HarnSpec？​

为什么使用 HarnSpec？​

HarnSpec 能加速我的开发吗？​

为什么有 2,000 Token 目标？​

框架对比​

HarnSpec 与其他 SDD 框架有什么区别？​

AI 集成​

HarnSpec 只适用于 Claude 模型吗？​

如何将 HarnSpec 集成到 Claude Code？​

为什么我的 AI 代理不遵循 HarnSpec 工作流？​

使用 HarnSpec​

如何升级或重新初始化 HarnSpec 而不丢失我的 Spec？​

如何查看 HarnSpec UI？​

如何使用 HarnSpec 管理多个功能开发？​

如何处理已完成 Spec 中的 Bug？​

故障排除​

我的Spec被 AI 编辑损坏了​

harnspec update 说"找不到Spec"​

frontmatter验证失败​

如何恢复已删除的Spec？​

CLI 命令不工作​

贡献与支持​

如何报告错误或请求功能？​

我可以贡献吗？​

我可以在哪里获得帮助？​

许可证是什么？​