AI-native code intelligence — one doc captures your project's contracts, invariants, intent, and risks, so every conversation starts informed.
让 AI 在新对话中读一份文档就掌握代码全貌，无需每次重新通读全量源码。
让 AI 辅助开发时，最大的隐性成本是重复解读源码：每开一个新对话，AI 都要把项目文件重新通读一遍才能动手，几十万 Token 就此烧掉。
Code Intel 把代码的理解层一次性沉淀成一份文档——不只是"哪个文件在哪"，而是理解代码所需的语义：
- 公共契约 — 每个 API 的签名、前置条件、副作用、返回约定
- 关键不变量 — "调用前必须初始化 X""失败时回滚事务""就地修改入参"
- 非显然意图 — 源码命名看不出的 why，例如"这里去空白是为兼容旧版 token 格式"
- 数据流与依赖拓扑 — 请求怎么流转、改一处会波及哪些模块
- 风险标注 — 复杂度热点、高耦合、隐式依赖、异常缺口，每条带置信度
AI 读这一份文档即可规划并推理绝大多数改动，只在最终确认行号、落地编辑时才打开源码。源码依然是行级真相，但对"这模块做什么、怎么用、改动波及哪里"，文档给出可信的自给自足答案。
Tier A 核心文件深度精读，提取契约、不变量与意图，而非仅罗列文件名。这是 Code Intel 区别于普通"文件树导航"的根本。
不是所有文件都值得逐行读。Code Intel 按 Hub 影响力 + 入口距离 + 接口密度加权打分，把文件分成三层，各按不同深度处理：
| 层级 | 阅读深度 | 记录内容 |
|---|---|---|
| A · 核心枢纽 | 深度精读 | 契约、完整签名、不变量、意图、依赖图、关键类型 |
| B · 业务逻辑 | 标准阅读 | 职责 + API 清单 + 关键副作用 |
| C · 外围文件 | 表面扫描 | 路径 + 一句话职责 |
基于可量化的结构特征生成，每条带置信度（高 / 中 / 低）：
| 标注 | 检测依据 |
|---|---|
| 🔴 复杂度热点 | 行数 >300 / 嵌套 >4 / 参数 >5 |
| 🟡 高耦合 | 被 10+ 模块引用（≥20 且文件小 → 高置信） |
| 🟠 隐式依赖 | 全局变量、模块级可变状态 |
| 🔵 异常处理缺口 | 空 catch，区分高危（吞数据）与低危（吞清理） |
| ⚪ 硬编码密钥 | 疑似 key / token / 密码字面量 |
| ❓ 理解缺口 | AI 坦诚标注"这段没看懂意图" |
🔒 严格规则： 只描述结构特征，绝不断言"这是 bug"。LLM 不执行代码，判断权始终交给开发者。
不简单按目录切分，而是三层算法：交叉密度分析（两目录频繁互引 → 建议合并）+ 内聚度检测（utils/ 下文件互不引用 → 标记松散集合）+ 循环依赖检测（双向依赖在拓扑图上画双向箭头）。
内置 5 套语言专项检查清单，按需载入——只读检测到的语言，主上下文保持精简。
| 语言 | 专项关注点（举例） |
|---|---|
| TypeScript / JavaScript | 类型断言安全、Promise 异常、DI 容器隐形依赖 |
| Python | 可变默认参数、asyncio 阻塞调用、装饰器签名覆盖、元类隐形构造 |
| Go | goroutine 泄露、channel 关闭语义、nil interface 陷阱、context 传播、init 隐形入口 |
| Rust | unsafe 安全不变量、Send/Sync 手动实现、async/.await 取消安全、宏展开路径 |
| Java / Kotlin | 反射安全边界、注解处理器生成代码、checked exception 传播、Kotlin 空安全 !!、协程作用域泄露 |
- 手动增量 — 只分析
git diff变更文件，Token 消耗与变更量成正比，与项目规模无关 - 版本标记 — 每个模块段落带 commit hash，一眼看出文档是否过时
将本仓库放入 Claude Code 的技能目录，重启后自动识别：
git clone https://github.com/ShiBeven/Code-intel.git ~/.claude/skills/Code-intel目录结构：
~/.claude/skills/Code-intel/
├── SKILL.md # 主指令：编排逻辑 + 硬规则（技能触发时载入，保持精炼）
├── checks/ # 5 套语言专项清单（Phase 2 按检测到的语言载入）
│ ├── typescript.md
│ ├── python.md
│ ├── go.md
│ ├── rust.md
│ └── java-kotlin.md
├── rules/
│ └── risk-detection.md # 风险检测规则手册（Phase 3 载入）
├── references/
│ ├── doc-templates.md # 文档与报告模板（Phase 4 生成前一刻载入）
│ └── incremental-update.md # 增量更新流程（仅更新触发时载入）
└── README.md
在 Claude Code 中直接调用：
# 在当前项目生成完整理解层文档
/Code-intel
# 指定输出目录
/Code-intel --output docs/architecture
# 增量更新：只分析自上次提交以来的变更
/Code-intel --diff HEAD~1
# 大项目按模块拆分输出
/Code-intel --output-format split
# 重新分析单个模块（失败恢复）
/Code-intel --module auth
# 手动指定文件优先级
/Code-intel --level A src/critical/auth.ts
# 强制指定语言（跳过自动检测）
/Code-intel --lang goCode Intel 分五个阶段执行，全程可由用户在关键节点介入调整：
Phase 1 · 扫描 枚举文件、读取项目已有文档、检测语言、构建引用图、加权分层
↓ （呈现层级分布与模块边界，用户可调整后确认）
Phase 2 · 分层阅读 Tier A 深读提契约/意图 · Tier B 标准 · Tier C 扫描
↓ （大项目自动并行，每 agent 一模块）
Phase 3 · 风险图 按 rules/risk-detection.md 提取结构风险，逐条标置信度
↓
Phase 4 · 生成文档 默认单文件 PROJECT_DOC.md：总览 + 数据流 + 模块契约 + 风险图 + 符号索引
↓ （并在 CLAUDE.md 写入指针，让后续对话自动发现文档）
Phase 5 · 完成报告 输出规模、风险统计、下一步建议
分层评分模型（决定阅读深度，不以文件名为依据）：
| 维度 | 权重 | 计量 |
|---|---|---|
| Hub 分 | 40% | 被引用次数，min(引用数/15, 1.0) |
| 入口分 | 30% | 是否为声明入口点 / 入口 2 跳内 |
| 接口分 | 30% | 导出公共符号数 / 文件行数 |
得分 ≥0.65 → Tier A，≥0.25 → Tier B，其余 → Tier C。测试文件、纯类型/常量文件、静态资源恒为 Tier C。
默认生成单文件，AI 一次读取即掌握全貌：
docs/PROJECT_DOC.md 架构总览 + 核心数据流 + 各模块契约 + 风险图 + 符号索引
大项目（--output-format split）按模块拆为附件：
docs/
├── PROJECT_DOC.md Layer 1 + 风险图 + 符号索引
└── modules/
├── auth.md
├── dashboard.md
└── ...
模块契约片段示意：
## 模块: auth
> 同步: commit `a1b2c3d` — 2026-07-05 | Tier 分布: A: 3 / B: 7 / C: 2
### 公共 API 契约
| 符号 | 签名 | 用途 | 契约 / 不变量 |
|---|---|---|---|
| `verifyToken` | `(token: string) => UserPayload \| null` | 校验并解码 | 过期或签名错返回 null 而非抛异常；会去除首尾空白（兼容旧版格式） |
| `login` | `async (creds: LoginDTO) => Session` | 认证用户 | 副作用：写入 session 存储；失败抛 AuthError || 参数 | 效果 |
|---|---|
--output <path> |
指定输出目录（默认 docs/） |
--output-format split |
大项目按模块拆分 Layer 2（默认单文件） |
--lang <lang> |
强制使用指定语言清单 |
--skip-tests |
跳过测试文件（默认已归 Tier C） |
--level <A|B|C> <file> |
手动覆盖指定文件的阅读层级 |
--diff <range> |
指定增量更新的 diff 范围（HEAD~1、main..feature） |
--module <name> |
重跑单个模块（失败恢复） |
| 场景 | 推荐用法 |
|---|---|
| 让 AI 辅助开发 | 把文档作为上下文喂给 AI，精准规划而非全量重读 |
| 新人接手项目 | 从架构总览开始，按文档内"阅读路径"走 |
| 排查线上 Bug | 先看风险图找热点，再查符号索引定位函数 |
| 修改核心模块 | 看模块契约的"被依赖"列表，评估改动影响面 |
| Code Review | 对照风险图，检查改动是否落在高风险区域 |
| 原则 | 含义 |
|---|---|
| 承载语义，回源码定位 | 文档承载理解所需的契约与意图，AI 据此规划推理；落地编辑时回源码确认行号 |
| 不假装能检测 Bug | LLM 不执行代码，只描述结构特征。标注的是"值得关注"，非"一定是错" |
| 坦诚标注不确定性 | 看不懂就标"理解缺口"，绝不猜测编造 |
| 版本标记不可缺 | 没有 commit hash，无从判断文档描述的是哪个版本 |
| 技能自身也省 Token | 主指令保持精炼、硬规则置顶；模板/规则/清单按阶段即时载入，读到即用，不受长文本注意力衰减影响 |
欢迎 Issue 与 PR。可贡献的方向：
- 新增语言专项检查清单（参照
checks/现有格式） - 完善风险检测规则（
rules/risk-detection.md） - 改进分层评分模型或模块边界算法
提交前请确保改动与现有文档风格一致，并在 PR 描述中说明动机与验证方式。