# Repo Map

更新时间: `待补`
维护责任: `项目 maintainer / owner`

## 1. 仓库目标

- 项目一句话描述: `待补`
- 主要用户: `待补`
- 核心业务域: `待补`

## 2. 从哪里开始读

- 第一步先读: `AGENTS.md`
- 第二步再读: `docs/ai/architecture-brief.md`
- 第三步按任务进入:
  - 前端 / 页面: `待补`
  - 后端 / 服务: `待补`
  - 数据 / schema: `待补`
  - 测试 / 验证: `docs/testing/*`
  - 规则 / driver: `docs/harness/*`, `tools/harness/*`

## 2.1 上下文索引最小字段

- 代码入口: 关键命令、路由、脚本、页面或服务入口
- 上游调用方: 谁会触发这个入口
- 下游依赖: 入口继续调用哪些模块、脚本、服务或接口
- 类型 / 契约入口: 类型定义、contract、schema 或导出面
- 测试入口: 关联测试、验证命令或证据目录
- 配置入口: `.codex/*`、环境变量、配置文件、manifest
- 风险入口: 权限、状态流转、数据边界、外部依赖、迁移或回滚
- 领域入口: 核心实体、业务规则、不变量、领域逻辑所在模块
- 禁改区: 当前任务默认不要碰的区域

## 3. 关键目录

| 路径 | 用途 | 可修改性 | 备注 |
| --- | --- | --- | --- |
| `src/` 或主代码目录 | 主实现代码 | `待补` | `待补` |
| `docs/ai/` | 导航层和快速摘要 | 可改 | 先填当前项目事实 |
| `docs/harness/` | 规则、治理、trace、使用说明 | 可改 | driver / harness 项目通常保留 |
| `docs/testing/` | 测试左移真相源 | 可改 | feature_impl 前置输入 |
| `docs/knowledge/` | 项目长期知识沉淀 | 可改 | 归档后维护 |
| `tools/` | 脚本和工程工具 | 谨慎 | 改后补验证 |
| `待补目录` | `待补` | `待补` | `待补` |

删除不适用目录，补齐真实目录名。

## 4. 关键依赖关系

- `待补`: 入口 -> 核心模块 -> 下游依赖
- `待补`: 页面 / API -> 状态 / 服务 -> 存储 / 外部系统
- `待补`: 构建 / 测试 / 发布链路

## 5. 常用命令

```powershell
git status --short
git diff --check
待补验证命令
```

只保留当前项目真实存在且可运行的命令。

## 6. 禁改区

- 不得伪造完成状态、测试结果、trace 或 review 结论。
- 不得跳过 `owned_paths`、公共契约、验证命令和必要文档更新。
- 不得把 token、cookie、私钥、密码或生产敏感数据写入仓库、trace 或文档。
- `待补项目禁区`

## 7. 任务入口

- Feature plan 所在位置: `task.json` 或项目等价任务源
- Product docs 所在位置: `待补`
- Domain model 所在位置: `待补`
- Design docs 所在位置: `待补`
- Contract 所在位置: `待补`

## 7.1 调用链与影响面提示

- 关键调用链:
  - `待补`
  - `待补`
- 影响面分析时至少回答:
  - 入口在哪里
  - 上游是谁
  - 下游是谁
  - 受影响文件有哪些
  - 受影响测试和验证命令有哪些

## 8. 子目录规则索引

| 路径 | 本地规则 | 触发场景 |
| --- | --- | --- |
| repo root | `AGENTS.md` | 全局任务边界和阅读入口 |
| `待补目录` | `待补目录/AGENTS.md` | 该目录有独立职责、边界或测试方式 |

## 9. 维护规则

- 新增独立模块、目录入口、测试命令或架构边界时，同时更新本文件和最接近的子目录 `AGENTS.md`。
- 如果某条规则只在局部目录生效，不要继续堆到根 `AGENTS.md`。
- 初始化后尽快删掉本文件中的 `待补` 占位，避免后续会话把模板文本误当项目事实。
