Narness

Narness 是「研究 + 文档 + Claude Code 工具集」项目，阐述并落地一套工程化思想：

能用代码、hook、脚本约束 AI agent 行为的，优先用这些，而非提示词。因为 agent 很可能不按提示词办事；脚本、hook 能让 agent 发现实现有问题，并指导其正确行为，从而保证长程任务的正确性。

理念

提示词是软约束，agent 可能忽略；脚本、hook 是硬约束，agent 无法逃避。Narness 用「约束层级阶梯」（L0 提示词 → L5 编译期）组织方法论，并提供插件把约束落地为代码。

目录

• docs/theory/ — 理论研究文档
• docs/reference/ — 具体工具的 harness 工程化参考
• plugins/narness-rust/ — Rust harness 工程化插件（skill + hook + 脚本）
• cli/ — narness 环境检查器（npm 包）
• .claude-plugin/marketplace.json — marketplace 定义

快速开始

安装 marketplace 后安装 narness-rust 插件：

claude plugin marketplace add <本仓库地址>
claude plugin install narness-rust

理论文档

• 为什么不能只靠提示词
• 约束层级阶梯
• 决策准则
• 长程任务的正确性

参考文档

• Rust 测试 Harness 工程化（nextest + llvm-cov + LLM 反馈）
• Git Hooks（提交/推送时机的 harness 执行）
• Claude Code Hooks（agent 工具调用时机的 harness 执行）
• Codex Hooks（OpenAI Codex CLI 的 harness 执行）

环境检查

cli/ 是一个 npm 包，项目根目录放 .narness.toml 声明 agent 运行环境要求，用 npx narness 检查：

[[checks]]
type = "version"
name = "node"
min = "22"

[[checks]]
type = "exists"
name = "rg"

npx narness           # human 报告（失败项含修复建议）
npx narness --json    # 结构化输出（供 hook/CI 消费）