spec-anchor — 基于AI自动标注的SPEC-Code追溯矩阵生成器

在AI辅助开发的SPEC-driven工作流中，开发者通过SPEC.md定义需求条目，并通过CLAUDE.md铁律约束AI在生成代码时自动带上@implements REQ-NNN注释标注。但传统追溯工具（IBM DOORS、Jama Connect等）太重型，需要手动标注，缺少一款轻量级的CLI工具来自动完成需求到代码的关联追溯。spec-anchor填補了这一空白，实现AI自动标注与自动追溯的闭环。

核心功能模块： • trace命令：解析SPEC.md提取需求条目（REQ-NNN格式），递归扫描源代码目录，通过两层匹配策略（Layer 1: @implements精确匹配；Layer 2: 关键词启发式兜底）关联需求与代码实现，生成Markdown/JSON格式的追溯矩阵 • impact命令：支持git提交范围或diff文件的反向影响分析，展示代码变更影响了哪些需求条目及其变更行数 • check命令：缺口检查，列出未实现和仅启发式匹配的需求，提供覆盖率统计 • 支持8种语言（Python/JS/TS/Go/Java/Rust/PHP/Ruby/Elixir）的函数名提取与注释识别，内置中英文关键词映射和同义词扩展 业务流程：开发者在SPEC.md中定义需求→AI生成代码时自动带@implements注释→运行spec-anchor trace生成追溯矩阵→运行spec-anchor impact查看变更影响→在PR中附上矩阵供reviewer审查

整体架构和设计思路：项目采用模块化分层架构，Python 3.10+开发，基于Click CLI框架构建命令行接口。核心数据流为：spec_parser.py解析SPEC.md提取需求实体 → scanner.py递归扫描源码执行Layer 1（@implements正则匹配）和Layer 2（函数名提取）→ keywords.py处理中英文关键词映射、同义词扩展和置信度评分 → matrix.py/impact.py生成输出报告。cache.py通过SHA256哈希实现增量扫描缓存，避免大型仓库重复全量扫描。项目严格遵循TDD开发，从SPEC定义→测试先行→实现→代码审查→自动验证，形成了完整的质量闭环。 负责模块和结果：该项目为独立开发的完整CLI工具。截至v0.2版本，完成10个核心模块的实现，通过150+个单元测试（覆盖率86%），覆盖8种编程语言的函数名正则匹配。所有验收标准（9个维度）一次性通过，mypy类型检查通过，ruff lint零错误。 遇到的难点和解决方案： • 中文需求标题匹配：内置2字符滑动窗口+中英文关键词映射表，每个CJK词组（如"注册"）映射到对应英文关键词集（register/create/signup），无需外部NLP依赖即可处理中文标题 • Windows平台编码问题：git diff输出GBK乱码，通过设置PYTHONIOENCODING=utf-8环境变量解决，并通过文件读取的errors="replace"容错 • @implements注释距离限制：注解必须紧贴函数定义（不超过5行），否则Layer 1扫描失败。扫描引擎实现了5行内搜索+多语言回退机制，并在文档中明确了此限制 • 跨语言注释格式统一：为8种语言定义了统一的@implements REQ-NNN注释格式，在语言检测模块中通过文件扩展名路由到对应的正则提取器