ln-612-semantic-content-auditor

路径： 文件路径（references/、../ln-*）均相对于此技能目录。

语义内容审查员（L3 工作器）

类型： L3 工作器

专门审查项目文档语义适用性的工作器。

目的与范围

• 验证文档内容是否符合其声明的 SCOPE 和文档类型
• 检查内容是否符合项目目标（价值贡献）
• 向协调器返回结构化问题，包含严重程度、位置和修复建议
• 不根据代码库核实事实

目标文档

仅针对项目文档调用（不包括参考资料／任务）：

文档	核查重点
AGENTS.md / CLAUDE.md	入口说明保持范围明确、便于导航，且不包含无关内容
docs/README.md	导航范围正确，描述相关
docs/documentation_standards.md	标准适用于此项目类型
docs/principles.md	原则与项目架构相关
docs/project/requirements.md	需求范围完整，不含过时条目
docs/project/architecture.md	架构范围涵盖所有层
docs/project/tech_stack.md	技术栈范围符合项目实际情况
docs/project/api_spec.md	API 范围涵盖所有端点组
docs/project/database_schema.md	架构范围涵盖所有实体
docs/project/design_guidelines.md	设计范围涵盖当前使用的组件
docs/project/infrastructure.md	基础设施范围涵盖所有部署目标
docs/project/runbook.md	运维手册范围涵盖设置与运维

排除： docs/tasks/、docs/reference/、docs/presentation/、tests/

输入

必须读取： 加载 references/audit_worker_core_contract.md、references/docs_quality_contract.md、references/markdown_read_protocol.md 和 references/mcp_tool_preferences.md。 工具策略：你可能作为隔离的子 Agent 运行，宿主的 AGENTS.md 不在作用范围内，因此读取、搜索和编辑文件时默认优先使用 hex-line MCP。仅当 MCP 行为不明确时，才加载 references/mcp_integration_patterns.md。

协调器每次调用时提供：

字段	描述
doc_path	要审查的文档路径（例如 docs/project/architecture.md）
output_dir	报告输出目录（来自 contextStore）
project_root	项目根目录路径
tech_stack	检测到的技术栈

对于此仅处理文档的工作器，hex-line 为可选工具。如有可用，可用它概览大型 Markdown 文件；否则继续使用内置的 Read/Grep/Glob/Bash，不要因 MCP 不可用而中止。

工作流

阶段 1：提取标题和契约

1. 先读取文档标题和顶部章节
2. 解析：
   • SCOPE
   • DOC_KIND
   • DOC_ROLE
   • READ_WHEN
   • SKIP_WHEN
   • PRIMARY_SOURCES
3. 若没有 SCOPE 标签，则根据文档类型推断
4. 若缺少 DOC_KIND，则根据共享契约推断预期类型
5. 记录声明的用途和路由边界

第 2 阶段：文档类型感知语义审计

根据文档类型进行判断：

DOC_KIND	主要语义问题
index	是否能高效地引导读者，避免堆砌过多深入的事实信息？
reference	是否准确、足够完整且易于查找？
how-to	操作步骤是否可执行且顺序正确？
explanation	是否建立了恰当的心智模型并说明理由？
record	是否保留了决策过程和后果？

根据已声明的范围和文档类型分析文档：

检查项	发现类型
不符合范围的章节	OFF_TOPIC
未覆盖的范围方面	MISSING_COVERAGE
超出范围的过多细节	SCOPE_CREEP
内容在其他位置重复	SSOT_VIOLATION

Agent 指令文件检查项（当被审计文件为 AGENTS.md 或 CLAUDE.md 时适用）：

检查项	发现类型	严重程度	建议
样式／格式规则（缩进、引号样式、尾随空格、命名约定）	NOT_A_LINTER	WARN	将其移至 Biome、Prettier、Ruff、EditorConfig 或 Claude Code Stop hook。指令文件会在每个会话中加载，并占用约 100 条指令的预算；确定性工具可以免费处理这些规则。
根目录中的条件式／非通用规则（when working on src/api/...、if modifying the billing service、for the Z service）	NON_UNIVERSAL_RULE	WARN	移至 .claude/rules/*.md，并添加 paths: frontmatter 过滤器（Anthropic 内置的路径范围限定功能）。非通用规则会通过 <system-reminder> 包装机制，使 Claude Code 倾向于忽略整个文件。
指向手动维护的 tasks/lessons.md 的自我改进循环规则	OBSOLETE_PATTERN	WARN	删除。Claude Code 的内置自动记忆功能已在 ~/.claude/projects/<project>/memory/ 中实现这一点；并行维护手工约定会浪费上下文。

以上三项都仅为 WARN——需要人工判断（样式规则是否有意为之？条件范围是否其实适用于整个项目？）。每项发现都引用 references/agent_instructions_writing_guide.md。

阅读策略：

• 先阅读标题和顶部章节
• 仅阅读判断所需的正文部分
• 只有在不阅读全文就无法安全进行语义判断时，才阅读整个文件

评分：

• 10/10：所有内容都符合范围，且范围得到全面覆盖
• 8-9/10：存在少量不相关内容或小的缺漏
• 6-7/10：部分章节不一致，覆盖不完整
• 4-5/10：存在明显不一致和重大缺漏
• 1-3/10：文档未能实现其声明的目的

第 3 阶段：评分与报告

根据范围契合度计算最终得分：

overall_score = weighted_average(coverage, relevance, focus)

覆盖度：范围覆盖得有多全面。相关性：内容有多大程度符合范围。聚焦度：是否不存在不相关内容。

评分算法

**必须阅读：**加载 references/audit_scoring.md。

输出格式

**必须阅读：**加载 references/templates/audit_worker_report_template.md。

根据 references/audit_summary_contract.md 编写 JSON 摘要。在托管模式下，调用方会同时传入 runId 和 summaryArtifactPath；在独立模式下，工作器会根据共享契约生成自己的、作用域限定于本次运行的制品路径。

将报告写入 {output_dir}/ln-612--{doc-slug}.md，其中 doc-slug 根据文档文件名生成（例如 architecture、tech_stack、agents_md）。

使用 category: "Semantic Content"，并包含以下检查项：scope_alignment、not_a_linter、non_universal_rule、obsolete_pattern（最后三项仅针对 AGENTS.md / CLAUDE.md 目标触发）。

根据 references/audit_summary_contract.md 返回摘要。

当 summaryArtifactPath 缺失时，将独立运行时摘要写入 .hex-skills/runtime-artifacts/runs/{run_id}/evaluation-worker/{worker}--{identifier}.json，并可选择在结构化输出中回显相同摘要。

Report written: .hex-skills/runtime-artifacts/runs/{run_id}/audit-report/ln-612--architecture.md
Score: X.X/10 | Issues: N (C:N H:N M:N L:N)

关键规则

应用已加载的 references/audit_worker_core_contract.md。

• 渐进式阅读： 优先按章节阅读；只有在需要做出可靠判断时才通读全文
• 推断范围： 如果没有 SCOPE 标签，则根据文档文件名推断预期范围
• 结合文档类型判断： 根据文档用途进行判断，而不是套用一套通用标准
• 避免误报： 宁可漏掉问题，也不要错误报告
• 精确标注位置： 每项发现都必须包含行号
• 提供可执行的修复建议： 每项发现都必须附上具体的修复建议
• 不做事实核查： 不要根据代码验证路径、版本或端点
• 共享类别注册表： 文档边界由 docs_quality_contract.md 确定；不要为每个文件另行制定范围规则

完成标准

应用已加载的 references/audit_worker_core_contract.md。

• 提取或推断标题约定
• 分析内容与范围的一致性（OFF_TOPIC、MISSING_COVERAGE、SCOPE_CREEP、SSOT_VIOLATION）
• 根据 DOC_KIND 进行语义判断
• 使用扣分算法计算分数
• 将报告写入 {output_dir}/ln-612--{doc-slug}.md（通过一次原子 Write 调用）
• 按照约定撰写摘要

参考文件

• 审计输出架构： references/audit_output_schema.md

---

版本： 2.0.0 最后更新： 2026-03-01