code-map

Files (2)

• SKILL.md
• knowledge-index.md · references/

SKILL.md (first lines)

# 代码地图（Code Map）

把已确认的代码架构与实际实现组织表达为可阅读、可追溯的地图。代码结构由 `code-architecture` 指导，本技能（Skill）解释当前实现；采用架构要求时先核对差异，不通过改地图掩盖不符合要求的代码。

## 包含什么

地图是在用户理解与真实事实源之间提供的解释性导航。按主题纳入相关规范、前后端实现及必要配置，说明“规范要求什么、实现怎样组织、两者怎样对应”；独立的成果文件树列出文章、地图、图源、展示与依据，区分事实源和解释成果。范围以阅读问题为准，不收录无关文件，也不把单纯资料目录当地图。

每个被阅读文件提供经核实的总体说明，解释职责、关键协作及边界；由网页先展示说明再显示源文件。源码变化后核对说明，缺少依据时如实标明。具体原生文件树格式及可选阅读字段见[网页阅读关联](references/knowledge-index.md)。

## 制作与维护

1. 确定项目（Project）、服务（Service）、业务模块或流程范围及阅读问题。读取相关规范、架构约束、实际代码与调用方，明确哪些内容不在本图范围内。
2. 按职责分区，先说明相关规范约束、实现职责和协作，再列带说明的可点击目录与文件。明确路径相对于哪个项目或服务根，只展示定位所需祖先及相关分支；使用原生 Markdown 嵌套列表与文件链接，加粗作者确认的业务目录，作为默认展开边界；祖先可见、业务目录内部默认收起，具体文件由用户继续展开。不把纯文本树和同内容宽表重复呈现。前后端沿用各自语言和框架；业务模块、接口、应用、数据访问、领域对象及共享能力只有实际存在才呈现。目录树是定位方式，不代替职责解释；相关资料清单也不是地图。
3. 解释实际存在的接口入口（HTTP、CLI 等）、应用用例、领域规则、数据访问和基础技术支撑怎样协作；没有某层或采用文件存储时如实说明。依据 `code-architecture` 判断职责，不为对齐模板补造目录或数据库。解释必要的依赖方向、数据归属和副作用。技能（Skill）以“中文用途（标识）＋职责”表格表达，链接进入详情；源文件名不是主标签。技能（Skill）工作方法与运行代码分开，工作协作不冒充函数调用。独立下探止于文件；方法可在文件说明中出现，不要求建设逐行索引。
4. 文件移动时更新位置；职责变化时核对解释与协作；删除时先查替代实现再解除失效引用。保留未受影响内容，当前实现、建议结构与未核实信息明确区分。
5. 核对每个已声明路径、职责与关键关联。记录来源观察、实际验证及未覆盖范围；目录存在不能证明语义正确。启用网页知识阅读时同时维护局部 `knowledge/index.yml` 的对象、成果与来源，不复制正文；具体格式与原生文档链接见[网页阅读关联](references/knowledge-index.md)。

## 输出

交付可独立阅读的地图文件：范围与阅读问题、职责分区、真实位置、关键协作、来源及限制。技术图（Technical Diagram）表达关系，地图表达职责怎样落到实现，解释文档按阅读问题引用两者。

## 前后端表达示例

后端订单模块：入口文件解释请求与参数，应用文件解释用例顺序，数据访问文件解释持久化，领域对象解释规则；分别核对真实命名和调用。没有领域层时如实说明，不能生成虚构目录。

前端订单功能：页面文件负责组织阅读与交互，完整业务组件承担表单或列表，客户端文件承接接口，公共组件只有实际复用才列入。说明为何归属该功能，不把所有组件都当成全局共享能力。

示例只是阅读方法。交付时以用户项目的真实文件、规范和调用关系替换抽象名字；来源无法核实时报告相关限制，继续其他有依据的部分。

From BuildrAI/Buildr, MIT.

More from BuildrAI/Buildr