codebase-context

# codebase-context — 项目代码库上下文管理 这是一份写给 AI 执行的 SOP。目的：把"每次开发前重读整个代码库"这个昂贵动作**一次性固化成结构化文档缓存**，后续开发直接加载文档当上下文。 - **scan（生产）**：系统通读源码，生成结构化参考文档。 - **dev（消费）**：加载参考文档进上下文辅助开发，开发完成后自动评估并回写更新文档。 ## 参数解析 调用格式：`/codebase-context <mode> [project-name] [--full]` 1. 解析第一个参数为 `mode`： - 值为 `scan` → 进入 scan 模式 - 值为 `dev` → 进入 dev 模式 - 缺失或为其他值 → 输出用法提示 `用法: /codebase-context <scan|dev> [project-name] [--full]` 并终止 2. 解析第二个非 `--` 开头参数为 `project-name`： - 已提供 → 直接使用 - 未提供 → 用 Bash 执行 `basename "$PWD"`，取当前工作目录最后一段路径名作为 project-name 3. 检查是否存在 `--full` 参数： - 存在且 mode=scan → 强制全量扫描 - 存在且 mode=dev → 忽略该参数并提示"--full 仅 scan 模式有效" 4. 设定文档目录 `DOC_DIR = {PROJECT_ROOT}/docs/codebase-context/`（存于项目工程内,随 git 提交、团队共享、换机不丢） 5. 设定项目根 `PROJECT_ROOT = 当前工作目录` ## 产物清单（固定 10 份文档 + 1 份元数据） 全部存于 `DOC_DIR` 下，文件名固定，不得增删改名： | 文件 | 内容 | | ---- | ---- | | 00-index.md | 索引与快速导航 | | 01-overview.md | 项目概述与技术栈 | | 02-directory.md | 目录结构 | | 03-architecture.md | 架构设计与模块关系 | | 04-api-routes.md | API 接口汇总 | | 05-data-models.md | 数据模型与类型 | | 06-core-modules.md | 核心模块（组件/Hooks/Store） | | 07-business-logic.md | 关键业务逻辑 | | 08-conventions.md | 编码规范与约定 | | 09-changelog.md | 文档变更记录 | | .scan-meta.json | `{"lastScanTime":"UTC时间","scanType":"full|incremental","projectRoot":"绝对路径"}` | --- ## scan 模式流程 ### 步骤 1：初始化 1. 按参数解析规则推导 project-name 1.5 **多项目���库检测（禁止扫仓库根）**：用 Glob 匹配 `*/package.json`、`*/*/package.json`（及 Cargo.toml/go.mod 等）——若当前目录自身不是单一项目根（无 src/），而多个子目录各含项目描述文件 → **列出候选子项目并让用户选定**（或用 project-name ...