> ## Documentation Index > Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt > Use this file to discover all available pages before exploring further. # 项目文件结构 > 了解 Comet 在项目里创建哪些目录和文件，以及每类文件分别承担什么职责——理解这个有助于恢复和排查。 Comet 把**需求事实、设计计划、运行状态和用户生成 Skill** 分开保存。理解这些文件的位置和职责，有助于你恢复中断的工作、排查状态问题，以及做跨设备/CI 集成。 所有恢复相关的状态都在**仓库文件里**（不依赖对话历史），所以换设备、换平台、上下文压缩后，`/comet` 都能从文件重建状态。详见[恢复中断的工作](/zh/guides/resuming-workflow)。

小鱼用小旗标记仓库文件里的需求事实、设计计划、运行状态和项目 Skill 分层

Comet 把可恢复的事实拆到仓库文件里，方便跨设备恢复、排查和协作

## 经典工作流目录 新建的 Classic 和双工作流项目默认使用文档目录布局： ```yaml theme={null} # .comet/config.yaml classic: artifact_layout: docs ``` `classic.artifact_layout` 可配置为 `docs` 或 `legacy`：`docs` 对应 `docs/openspec/`，`legacy` 对应仓库根目录的 `openspec/`。这是两种受支持布局的选择，不接受任意目录路径。 ```text theme={null} docs/ ├── openspec/ │ ├── config.yaml # OpenSpec 项目配置 │ ├── changes/ │ │ ├── / # 一个活跃 change │ │ │ ├── .openspec.yaml # OpenSpec 状态 │ │ │ ├── .comet.yaml # Comet 工作流状态（用户可读投影 + run_id 链接） │ │ │ ├── proposal.md # Why + What │ │ │ ├── design.md # How（高层） │ │ │ ├── tasks.md # 任务清单（- [ ] / - [x]） │ │ │ ├── specs//spec.md # delta spec │ │ │ └── .comet/ # Comet 运行产物（见下） │ │ └── archive/YYYY-MM-DD-/ # 已归档 change │ └── specs//spec.md # 当前主规格（归档时由 delta 合并） └── superpowers/ ├── specs/YYYY-MM-DD--design.md # 技术设计文档（Design Doc） ├── plans/YYYY-MM-DD-.md # 实施计划 └── reports/YYYY-MM-DD--verify.md # 验证报告（可选） ``` 已有 Classic 项目不会在升级时自动移动根目录 `openspec/`。如果想从旧布局迁移到 `docs/openspec/`，详见[迁移 Classic 布局](/zh/guides/classic-layout-migration)。 ### change 内的 .comet/ 运行产物 每个 change 目录下还有一个 `.comet/` 子目录，存运行期产物（多为 machine-owned，不要手工编辑）： ```text theme={null} docs/openspec/changes//.comet/ ├── run-state.json # Engine Run state（machine-owned） ├── state-events.jsonl # Classic 状态转换审计日志（append-only） ├── pending-action.json # 当前等待的 pending action ├── trajectory.jsonl # append-only 轨迹审计 ├── context.md # 当前 Agent 上下文 ├── artifacts.json # 产出的 artifacts 映射 ├── checkpoint.json # 一致性检查点 ├── handoff/ # handoff 交接包（design 阶段生成） │ ├── design-context.json # 默认模式机器索引 │ ├── design-context.md # 默认模式可读摘要 │ ├── spec-context.json # beta 压缩模式 │ ├── spec-context.md │ └── brainstorm-summary.md # brainstorming 恢复检查点 └── subagent-progress.md # subagent 调度检查点（仅 subagent 模式） ``` brainstorm-summary.md 和 subagent-progress.md 是 恢复锚点——上下文压缩后 Agent 会重载它们继续。你通常不需要读这些文件，但知道它们在哪有助于排查。 ## Comet 配置和运行目录 项目根的 `.comet/` 目录存放项目级配置和各能力的运行数据： ```text theme={null} .comet/ ├── config.yaml # 项目级 Comet 配置（共享入口及 native/classic 默认值） ├── skill-preferences.yaml # /comet-any 的项目级 Skill 偏好 ├── skills/ # 项目 Skill 池（按名覆盖内置 Skill） ├── runs// # standalone Engine Run 状态 ├── skill-snapshots// # 不可变 Skill 快照 ├── bundle-authoring/ # /comet-any 创作状态 ├── bundle-drafts/ # Bundle draft ├── bundle-factory-plans/ # Factory plan ├── bundle-evals/ # eval 证据 ├── bundles/ # 已发布 Bundle └── tmp/ # 临时文件 ``` 不同项目不一定都会出现所有目录——**只有使用对应能力后才会创建**（例如没用过 `/comet-any` 就不会有 `bundle-*` 目录）。 仓库根目录的 .comet.yaml 或 comet.yaml 不是 Comet 配置文件，也不会作为工作流状态读取。项目默认配置只放在 .comet/config.yaml；新项目的 Classic change 状态放在 docs/openspec/changes/\/.comet.yaml ，保留旧布局的项目仍使用 openspec/changes/\/.comet.yaml。 ## 目录和文件职责 | 路径 | 职责 | 谁读写 | | -------------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------- | | `docs/openspec/changes//.comet.yaml` | Comet 工作流状态（phase、workflow、language、build 决策、verify\_result、run\_id 链接） | Agent 读写，用户可读 | | `docs/openspec/changes//.comet/run-state.json` | Engine Run 细节（currentStep、pending、trajectory、artifacts） | machine-owned，不要手工编辑 | | `docs/openspec/changes//.comet/state-events.jsonl` | Classic 阶段转换审计，记录 event、source 和 effects | Comet 追加写入，用户可读 | | `docs/openspec/changes/` | 活跃 change 和归档 change | OpenSpec + Comet | | `docs/openspec/specs/` | 当前主规格（归档时由 delta 合并进来） | OpenSpec | | `docs/superpowers/specs/` | 技术设计文档（Design Doc） | Superpowers + Comet | | `docs/superpowers/plans/` | 实施计划 | Superpowers + Comet | | `.comet/config.yaml` | 项目级 Comet 配置。`native.*` 与 `classic.*` 分别控制两套工作流默认值 | 用户编辑 | | `.comet/skill-preferences.yaml` | `/comet-any` 偏好（advisory/strict、prefer/require） | 用户编辑或 `/comet-any` 生成 | | `.comet/skills/` | 项目 Skill 池（按名覆盖内置） | `comet skill add` | | `.comet/runs//` | standalone Engine Run 状态 | `comet skill run --run-id` | | `.comet/bundles/` | 已发布 Bundle | `comet publish run` | ## 哪些该提交到 git * **应该提交**：当前 Classic 产物根（新项目为 `docs/openspec/`，保留旧布局的项目为 `openspec/`）、`docs/superpowers/`、`.comet/config.yaml`、`.comet/skill-preferences.yaml`。这些是事实来源，提交后才能跨设备恢复。 * **看情况**：`.comet/skills/`、`.comet/bundles/`（团队共享则提交；个人本地则忽略）。 * **通常忽略**：`.comet/tmp/`、运行期临时文件。 .comet.yaml 和 run-state.json 的边界：.comet.yaml 保存 用户可理解的工作流投影（phase、build\_mode、verify\_result 等），只通过{' '} run\_id 链接到 Engine；完整的 Run 细节在 run-state.json。 state-events.jsonl 只解释成功状态转换的历史，不是当前状态来源。所以你看{' '} .comet.yaml 就能理解当前进度；排查状态为何变化时，再看事件日志。 ## 下一步 * [恢复中断的工作](/zh/guides/resuming-workflow) — 这些文件如何支撑 `/comet` 恢复 * [状态损坏与恢复](/zh/guides/state-recovery) — 状态坏了怎么排查 * [状态与配置](/zh/concepts/state-management) — `.comet.yaml` 字段详解