# 目录与路径约定

[English](./en/directory-conventions.md)

## 核心边界

- `.Knowledge/`：**知识环**——业务知识文档与机读路由（见 [体系与原理 §2 多层记忆](./体系与原理.md)）
- `.task/`：**任务环**——变更追踪与跨会话续作（不在 `.Knowledge/` 内）
- `配置根`（`.cursor/.claude/.codex`）：**规则环 + 技能环**入口

Memory Coding 四环总览见 [体系与原理 §1](./体系与原理.md)。

---

## 目录职责

| 路径 | 职责 |
| --- | --- |
| `.Knowledge/stock-docs/` | **L3** 架构、终稿、沉淀长文档 |
| `.Knowledge/req-docs/` | **L3** 需求澄清、技术方案长文档 |
| `.Knowledge/topics/` | **L2** 主题摘要（硬约束、边界、路由指针） |
| `.Knowledge/template/` | 终稿/技术方案模板 |
| `.Knowledge/index.md` | 人类可读索引 |
| `.Knowledge/manifest-routing.json` | **L0** 机读路由骨架（task/topic/`topicDependencies`/`topicMetadata`） |
| `.Knowledge/matchers/*.json` | **L1** 关键词分片（`id/includeAny`），由 `matcherPath` 直链；**match** 只读一片 |
| `.Knowledge/migration-report.md` | `f2s-kb-migrate` 落盘的迁移对照表与拟删除路径列表 |
| `.task/` | 变更追踪任务清单目录（`active/` 进行中，`completed/` 已归档且目录名为 **`<YYYYMMDD>-<task-name>`**（日期在前），`todo.json` 活跃任务索引）；仅当 `changeTracking.*` 为 `true` 或显式调用 `f2s-req-plan` 时创建 |
| `配置根/rules/` | 规则文件（Cursor `.mdc`，Claude `.md`） |
| `配置根/skills/` | 技能定义（`SKILL.md`） |
| `配置根/template/` | （废弃）不再写入；历史目录可清理 |
| `.codex/AGENTS.md` | Codex 统一入口与加载说明 |
| `flow2spec.config.json` | 项目根配置，控制 `subAgent`、`switchAgentVerification`、`changeTracking`（嵌套对象，含 `feat` / `fix` / `implement` 三个子项） |

> 多端提示与路径表见 [使用说明 § 一](./使用说明.md)（详表单点维护）；**权威仍为 Read(`flow2spec.config.json`)**。

---

## 路径约束

1. `.Knowledge/topics` 是知识路由主题层，允许并鼓励通过 `f2s-*` 技能维护。
2. `f2s-kb-build` 从 `.Knowledge/stock-docs` 读，更新 `.Knowledge/topics`、`.Knowledge/index.md`、`.Knowledge/manifest-routing.json`、`.Knowledge/matchers/*.json`。
3. 实现类任务统一读取 `.Knowledge/req-docs/*.md`。
4. `manifest-routing.json` 与 `matchers/*.json` 由 `f2s-*` 技能流程维护；不再使用 `.Knowledge/manifest-matchers.json`（`flow2spec init` 会删除遗留文件）。

---

## 主题元数据

`manifest-routing.json.topicMetadata` 是 topic 的机读治理元数据，只用于盘点、过滤、路由审计、升级补缺和阅读预期；不参与 matcher 命中，不决定是否读取 topic，不作为执行强制性的事实源，也不驱动 `topicId` 或文件名变化。执行强制性始终以 `AGENTS.md`、rules、skills 与 topic 正文中的明确要求为准。

`topicMetadata` 独立于 `topicPaths`，key 必须是 `topicPaths` 中已存在的 topicId。新增 topic 时有明确证据可同步写入；仅补分类不得创建 topic、重命名 topic 或拆分 topic。

| 字段 | 取值 | 说明 |
| --- | --- | --- |
| `primary` | `feature` / `module` / `config` / `policy` | 单值主分类。取 topic 最核心的性质，读 topic 正文后写入。 |
| `tags` | `feature` / `module` / `config` / `policy` 数组 | 可选次要分类，不得与 `primary` 重复。 |
| `confidence` | `manual` / `inferred` | `manual` 为人工确认；`inferred` 为有明确证据推断；证据不足时不写 metadata，并在摘要列为待确认。 |

类型含义：

| 类型 | 阅读预期 |
| --- | --- |
| `feature` | 已落地业务/产品能力背景 |
| `module` | 目录、包、模块边界与工程结构 |
| `config` | 配置项、开关、默认值、初始化参数 |
| `policy` | 流程、规则、约束、门禁、禁止项、agent 编排、技能步骤 |

## 主题粒度

topic 是路由摘要与关键边界，细节放在 `stock-docs/`。若对应 stock-doc 超过 300–500 行、matcher `includeAny` 超过 12 个，或正文出现 3 个以上不相干职责域，建议拆成主 topic + 可独立命中的子 topic。

---

## 相关文档

- [使用说明](./使用说明.md)
- [命令说明](./命令说明.md)
- [体系与原理](./体系与原理.md)
- [使用案例-模拟对话](./使用案例-模拟对话.md)
- [项目里程碑](./项目里程碑.md)