feat(codemap): 补符号 summary 语义层(dev 写作纪律 + 抽取 + embedder 升级)

[pcliangx]

背景 / Why

复用检查(#28)的精度取决于 codemap 索引了多少语义信号。这条 issue 是复用门的供给侧/索引侧——从 #28 拆出单独追踪。

已核实的现状(codemap 内部):

• codemap 的 search/embedder.py 今天只吃 name + signature + file_path(纯确定性字段)。
• 注释白纸黑字:设计原定 summary + name,但「LLM summary 层(07 §5)未实现、summary 恒 None」,故降级用确定性字段;并留了口子「summary 层落地后此处升级输入即可,存储/检索不变」。
• 抽取层(extract/*.py)根本没抽 docstring,符号只有 name/signature/行号/type。

含义:现在语义检索 / 重复检测的 recall 基本只到「名字/签名相似」——「同样的行为、换个名字重写一遍」查不出来,正是「class/function/method 废弃重造」最难抓的那种。summary 插槽现成、就差填。

本 issue 的思路:让 dev agent 写码时顺手写 intent 语义(比 LLM post-hoc 生成更省、更准、还兼当人读文档),抽取进 summary 字段,embedder 升级输入 → 大幅提升 #28 的召回精度。

验收标准 / AC

• AC-1: coding.md 加「符号语义写作纪律」——可复用面(导出 class/function、service 方法、shared util)必须写一行 intent(行为 + 输入/输出语义,不是复述签名);私有 helper 不强制(避免形式主义)。约定结构化写法(Python docstring 首行 / JSDoc @description / tag)让抽取可机械拉。6 个 dev 执行角色经 coding.md 继承。
• AC-2: codemap 抽取层拉 docstring/intent 进符号 summary 字段(现恒 None);Python / TS / Java 各自约定来源。
• AC-3: embedder 输入升级 name+signature → summary+name+signature(按 embedder.py 注释,存储/检索不变、只换输入);summary 为空时降级现状(兼容遗留/未注释符号)。
• AC-4: 诚实红线——写的语义仅作召回辅助,复用决策仍 verify 结构(structure_hash)+ 测试;summary 与签名/测试漂移 = feat(codemap): 复用校验门——符号级重复检测 + 强制复用审计 #28 复用审计的 review finding。known-limitations.md 登记「summary = model-authored,可能漂移」。
• AC-5:(协同 feat(codemap): 复用校验门——符号级重复检测 + 强制复用审计 #28,可选)summary 尽量锚到它实现的 AC/Requirement(Spec-Driven)——有测试兜底、比自由 docstring 更硬、不易漂移,并支撑「按能力查复用」(AC-N ↔ symbol 映射)。

关联

• Related issues: feat(codemap): 复用校验门——符号级重复检测 + 强制复用审计 #28(复用校验门——检查侧:codemap reuse/duplicates 子命令 + review 复用审计门)。本 issue = 供给侧(写码语义纪律 + 抽取 + embedder),两者合起来复用门才完整、精度才够。
• ADR: 待开 ADR-028(可与 feat(codemap): 复用校验门——符号级重复检测 + 强制复用审计 #28 同一 ADR 分两节,或本 issue 单列);先例 ADR-021
• Refs: tools/codemap/src/codemap/search/embedder.py(第 7-9 行:当前只吃 name+signature、summary 恒 None 的注释)· tools/codemap/src/codemap/extract/*.py(未抽 docstring)· docs/design/deeply-understand/06-semantic-search.md(§2 原设计 summary+name)· 07 §5(LLM summary 层未实现)· .claude/standards/coding.md · docs/known-limitations.md

备注

• 与 feat(codemap): 复用校验门——符号级重复检测 + 强制复用审计 #28 的边界:feat(codemap): 复用校验门——符号级重复检测 + 强制复用审计 #28 = 检查侧(找重复 + review 门);本 issue = 供给侧(喂语义,提升检查召回)。建议同 ADR-028 一并设计,但分两 issue 追踪实现。
• 目标版本:后续 MINOR(未定);「后续版本深化」追踪单。
• 来源:2026-07-15 maintainer 与 Claude 的设计讨论延伸(dev 写符号语义 → codemap 检查更精准)。

[pcliangx]

AC 处置（#29 关闭）：

• AC-1 coding.md 符号语义写作纪律 → ✅（feat: 防 AI 代码膨胀治理层（#28 复用门 + #29 符号语义 + #30 观测） #34）
• AC-2 抽取层拉 docstring→summary，Python/TS/Java → ✅（Python/TS feat: 防 AI 代码膨胀治理层（#28 复用门 + #29 符号语义 + #30 观测） #34 + Java feat(codemap): #29 AC-2 二期——Java adapter 抽 signature + Javadoc summary #37）
• AC-3 embedder 输入升级 summary+name+signature → ✅（feat: 防 AI 代码膨胀治理层（#28 复用门 + #29 符号语义 + #30 观测） #34）
• AC-4 诚实红线（summary 仅召回辅助）+ known-limitations 登记 → ✅
• AC-5 AC↔symbol 映射 → 砍（maintainer 决定）：无 driver、镀金——复用门现靠 signature/semantic 相似度（codemap duplicates/reuse）已在干，AC-5 加的「按 AC 查」轴没人提过需求；dev 写作摩擦（AC-1 已要求 intent docstring，再要 AC tag 是额外负担）；与 ADR-012 spec-driven（变更文件夹 AC 跟踪）重叠。出现「按 AC 查符号」真实用例时另开 issue。

另注（不在 #29 AC 范围，ADR-029 明确 defer 二期）：SQL/YAML/SFC/json adapter 的 signature/summary 抽取仍未做（AC-2 原文只点名 Python/TS/Java）。这 4 语言留真实多语言项目驱动时再做（YAGNI）。

doc 漂移：known-limitations.md「符号语义覆盖」行还写「Python/TS only」，Java 已在 #37 补——需改「Python/TS/Java」（1 行小修，单独跟进）。