参与贡献 · 开源，Apache 2.0 许可

在源头修一次，
每个项目都受益。

模板、规范或 hook 里的缺陷，最先出现在生成的项目中。在那里修，只修好一个项目；在 Nerviz 里修它的归属文件，之后生成的每个项目都会修好。所以最有用的报告，是维护者能够核实的报告。

1 个未关闭·37 个已关闭·10 个星标nerviz-ai/nerviz 的 issue，统计于 2026-10-27 →

§ 在生成的项目中

/report-issue 替你提交

在生成的项目中输入它，附上一段描述或一个经验总结文件。它选用仓库自己的 issue 表单，就缺少的证据询问一次，去掉所有能识别你项目的信息，搜索未关闭的重复 issue，并且只在你确认之后才发布。

# 在生成的项目中
› /report-issue <问题描述>
› /report-issue docs/lessons-learned/sonar-001.md

只有你能提交没有任何东西会链式调用 /report-issue。它只能手动调用，所以模型无法自行发布。
没有证据，就没有 issue每条陈述在任何改动之前都会对照 HEAD 的代码核实。没有文件、没有输出、无法复现的陈述只能以 needs evidence 关闭，所以不会被写出来。
只带痕迹，不带项目仓库是公开的，你的项目可能不是。issue 只写 Sonar 规则键、计数、.claude/ 内的路径、命令和 hook 输出。绝不写 src/ 下的路径、包名、类名、代码片段、项目 key 或服务器 URL。

步骤	做什么	何时停止
1 · 输入	一段自由描述，或 `docs/lessons-learned/` 下的一个文件	问过一次后仍未提供
2 · 版本	从 `.claude/.arch-provenance.json` 读取 `ref`、`commit` 和 `blueprint`，与最新 tag 对比	没有来源标记：不是 Nerviz 生成的项目
3 · 表单	Bug、feature 或 Sonar lessons，从仓库的 `HEAD` 获取。标题前缀、label 和字段都来自表单	表单无法获取
4 · 证据	Bug：入口、承诺该行为的 `.claude/` 文件、原样输出、复现步骤。Feature：一次具体的发生	询问后仍然缺少：什么都不写
5 · 正文	`docs/lessons-learned/<name>.issue.md`，每个表单字段一节，然后做隐私检查	—
6 · 询问	找到的重复 issue、版本警告、隐私改写：创建、先编辑，或不发布	`gh` 未认证：正文文件就是交付物
7 · 创建	`gh issue create --body-file …`；结果写入输入文件的 `## Issue` 行	—

落后于最新 release 只是警告，不会停止：新 release 可能已包含修复，/arch-adopt 可以把它拉进项目。

§ issue 表单

四种表单，每类报告一种

空白 issue 已禁用。/report-issue 读取的表单文件与网页相同，所以两者生成同样的 issue。

bug_report.yml
Bug report
标题 bug: Label bug
.claude/ 中的某个部分，行为与它自己文件所写的不同。
需要填写
- 发生在哪里：Nerviz、生成的项目，或两者
- 组件和确切的入口
- 承诺该行为的文件和行号，原文引用
- 原样输出、复现步骤，以及 /arch-doctor 的输出
- java、git、claude 的版本和操作系统
提交方式 /report-issue 或网页表单
feature_request.yml
Feature request
标题 feat: Label enhancement
某件事如今困难、重复或在无声中出错，而且没有文件作出相反的承诺。
需要填写
- 问题本身，而不是解决方案
- 应由哪种文件承载：规范、skill、agent、hook、CLAUDE.md 章节、MCP 服务器或文档
- 如何验证
- 它遵守的不变量，以及生成的项目是否也需要它
- 考虑过的替代方案
提交方式 /report-issue 或网页表单
new_blueprint.yml
New blueprint
标题 blueprint: Label blueprint
在 .claude/blueprints/ 中以数据声明的架构，不改动任何 skill、agent 或命令。
需要填写
- id、可读名称和一句话描述
- when_to_choose 和如实的 trade_offs
- build.layout、模块和依赖方向
- packages.map 和 architecture_paths
- _schema.md 的 6 条规则检查清单
提交方式 网页表单
sonar-lessons.yml
Sonar lessons
标题 sonar-lessons: Label sonar-lessons
生成项目中的 SonarQube 发现，追溯到产生它们的 .claude/ 部件。
需要填写
- 来源版本，取自 .arch-provenance.json
- 快照：quality gate 和计数，仅此而已
- 按归属列出的发现：规则键、数量、.claude/ 中的归属、来源
- 建议的修改，以及结构性教训
- 隐私确认：不含任何能识别被分析项目的信息
提交方式 /sonar-lessons，然后 /report-issue

在 GitHub 上打开表单 →

这些不是 issue

安全漏洞通过 security advisory 私下报告。绝不要提 issue，也不要用 /report-issue：两者都会公开它。
使用问题在提 issue 之前，先到 Discussions 询问某个功能如何工作。
不认同某个设计先读 .claude/decisions/。Bug 表单会要求你确认这是缺陷，而不是一项决策。

§ 能运行、有质量的代码

生成的代码不应变成技术债

harness 生成的一切，目标都是能运行、有质量的代码，而不是日后要有人买单的代码。SonarQube 发现的问题几乎从来不是个例：代码来自某个模板，某条规范允许了它，或者 .claude/ 什么都没说、模型自己做了决定。/sonar-lessons 找到这个归属，让修复落在之后每个项目都能拿到的地方。

/sonarqube-setup把扫描器加入根构建文件；还没有服务器时，再加一个本地 SonarQube 容器。只运行一次。
/sonar-lessons运行分析，通过 Web API 读取 quality gate、bug、漏洞、code smell、重复率和覆盖率。需要服务器在线和 SONAR_TOKEN；它从不负责配置这些。
sonar-NNN.md完整的教训保存在你项目的 docs/lessons-learned/ 中：路径、行号、代码片段，以及每组问题在归属处的修复。
/report-issue由你输入。它用 Sonar lessons 表单提交这份教训，并去掉项目的一切信息。

# 一次性：构建文件里的扫描器、一个服务器、一个 token
› /sonarqube-setup

# 完成一个功能后：分析、追溯、写下教训
› /sonar-lessons

# 然后提交到修复所属的地方
› /report-issue docs/lessons-learned/sonar-001.md

每组发现都有归属

来源	如何找到
原样复制的模板	被标记的写法出现在某个 `templates/*.example` 中：每个项目都会有这个问题
允许或要求它的规范	某条规范规定了被标记的形式，或明确允许它
Checkstyle 或构建配置	在 Sonar 有对应规则的地方，缺少检查或检查被关闭
测试模板教了这种模式	同样的查找，范围是测试模板
bootstrap 生成的代码	项目里没有对应模板：记为 `project-bootstrap` 加上文件的角色
没有归属：模型自己决定	没有规范、也没有模板覆盖这种写法。修复方式是新增一条规范

每次运行都与上一次对比：快照增加 Previous 和 Δ 两列，每组标记为新增、反复出现或已消失。目标是每一轮问题更少，而这里正是判断是否做到的地方。

§ 提交之后

任何改动之前，每条陈述都会被核实

维护者对你的 issue 运行 /triage-issue。一个没有写入工具的 agent 对照 HEAD 的代码核实每条陈述，并单独评判提议的修复。结论以评论和 label 的形式返回。

结论	含义
`duplicate`	另一个 issue 已覆盖同一个已确认的症状
`already-fixed`	在你的版本中成立，在 `HEAD` 中不成立：会注明修复的 commit
`by-design`	某条决策记录选择了这样做，而 issue 没有带来该记录未考虑过的事实
`confirmed`	核心症状已复现，通过文件、hook 模式或构建
`not-reproduced`	核心症状已核实，在 `HEAD` 中不成立
`needs-evidence`	没有能下结论的核实；会注明能下结论所需的那一项

完整流程，见文档 →

§ pull request

修改 harness 本身

蓝图和规范是最有用的贡献。这个仓库不是 Java 应用：要编辑的是指令文件、数据和一个 hook。第一个 PR 之前请先读 CLAUDE.md；评审依据的就是其中的 Invariants。

# JDK 21+、git 和 curl，别无其他
git clone https://github.com/nerviz-ai/nerviz.git
cd nerviz
java .claude/hooks/ArchHook.java doctor

# 提交 PR 之前
java .claude/hooks/ArchHook.java schema
claude plugin validate .claude/skills

不确定该写成规范、skill、agent 还是 hook？选错类型是评审中最常见的问题，/claude-code-architect-designer 正是为此而设。

CONTRIBUTING.md，含各类文件的规则 →

在源头修一次，每个项目都受益。

/report-issue 替你提交

四种表单，每类报告一种

Bug report

Feature request

New blueprint

Sonar lessons