文件与目录管理规则¶

结论：按生命周期和权威来源管理文件。一个内容只保留一个权威副本。

版本：V1.2
制定日期：2026-10-20
调研依据：主流归档方案调研与建议.md

1. 适用范围¶

本规则适用于 ~。

仓库级 AGENTS.md 可以增加约束。仓库级规则不能降低本规则要求。

2. 根目录边界¶

3. 分类顺序¶

按以下顺序判断。命中一项后停止。

1. 用户给出明确路径时，使用用户路径。
2. 由 macOS 或应用管理时，保留原位。
3. 属于 Git 源码时，放入 repo。
4. 属于固定版本工具时，放入 tools。
5. 属于活跃非 Git 工作时，放入 workspace/active。
6. 属于临时工作时，放入 workspace/scratch。
7. 属于长期文稿或证据时，放入 Documents。
8. 属于完成项目时，放入 archive。
9. 无法判断时，放入 Documents/inbox。

4. Documents 结构¶

Documents/
├── MANIFEST.md
├── inbox/
├── projects/
├── areas/
├── resources/
└── assets/

文档内容编写遵循 文档编写规则.md。

4.1 项目目录¶

Documents/projects/
└── PRJ-2026-001-covio/
    ├── README.md
    ├── deliverables/
    ├── evidence/
    └── metadata/

项目目录必须有 README.md。

README 至少写明目标、状态、负责人、来源和去向。

4.2 证据¶

• 证据放项目自己的 evidence/。
• 证据记录来源、日期和摘要。
• 正文引用证据路径或 ID。
• 不把同一证据复制到多个项目。

5. 项目标识¶

项目 ID 使用以下格式。

PRJ-YYYY-NNN-slug

示例：

PRJ-2026-001-covio

规则：

• ID 分配后不修改。
• 标题可以修改，ID 不修改。
• 归档沿用原 ID。
• 不在目录名前加入 00、10、20 等主题编号。
• 日期使用 ISO 8601，例如 2026-10-20。
• 交付物使用 YYYY-MM-DD-topic-vNN.ext。

6. 源码与工作区¶

6.1 repo¶

repo/
├── Covio/
├── Lidsleep/
├── ObsidianVault/
├── kmp-translator/
└── _worktrees/
    └── Covio/
        └── task-156/

• 一个目录对应一个仓库。
• 活跃项目必须有 Git 来源。
• 不提交 build、dist、node_modules 和缓存。
• worktree 不是独立仓库。
• worktree 不是归档单元。
• 新 worktree 使用 git worktree add。
• 移动 worktree 使用 git worktree move。
• 关闭 worktree 前保存提交或补丁。

6.2 workspace¶

workspace/
├── active/
│   └── <task>/
└── scratch/
    └── <task>/

• active 保存活跃非 Git 工作。
• active 默认每 14 天复核。
• scratch 保存临时脚本、日志、截图和测试输出。
• scratch 在任务结束前清理。
• 需要保留的临时结果移入 Documents。
• 唯一重要内容不得只存在 scratch。

7. 归档¶

完成项目进入以下目录。

archive/
└── 2026/
    └── PRJ-2026-001-covio/
        ├── bagit.txt
        ├── bag-info.txt
        ├── manifest-sha256.txt
        ├── tagmanifest-sha256.txt
        └── data/
            ├── README.md
            ├── deliverables/
            ├── evidence/
            └── metadata/

归档包遵守 RFC 8493 BagIt。

bag-info.txt 至少记录以下字段。

规则：

• 归档内容保持只读。
• 修改归档时，先恢复到 workspace/active。
• 修改后生成新的分发副本。
• 归档不等于备份。
• 删除前先审批。
• 删除前保留 30 天缓冲期。

8. 权威来源¶

9. 生成物¶

以下内容不归档。

• build/
• dist/
• node_modules/
• .gradle/
• 编译缓存
• 临时日志
• 可重新下载的安装包
• 未签名的临时二进制

发布件需要保留时，放入项目的 deliverables/。

10. 系统目录¶

以下目录不手工重组。

• ~/Library
• ~/Applications
• ~/Applications 以外的 App 包
• ~/.codex
• ~/.claude
• ~/.paseo
• ~/OrbStack
• macOS 管理的隐藏目录

需要清理时，使用应用自带功能。

11. 备份¶

• 当前环境未配置 Time Machine 目标。
• 正式迁移前配置本地备份。
• 至少保留一份异地或离线副本。
• 每季度执行恢复演练。
• 归档不能代替备份。

12. 迁移门槛¶

移动五个以上文件或目录时，执行以下步骤。

1. 生成迁移清单。
2. 检查目标冲突。
3. 检查 Git 和 worktree 状态。
4. 检查打开文件。
5. 生成迁移前摘要。
6. 执行试运行。
7. 分批移动。
8. 校验迁移后摘要。
9. 保留回滚记录。
10. 观察 14 天。

删除或覆盖用户数据前，必须得到用户明确确认。

13. 完成检查¶

• 主目录没有新增主题目录。
• Desktop 没有本任务临时文件。
• Downloads 没有本任务输出。
• workspace/scratch 已清理或登记。
• 项目有 README。
• 项目有唯一 ID。
• 归档遵循 BagIt。
• 归档有摘要清单。
• 权威来源唯一。
• 迁移摘要一致。

14. 版本记录¶