# 经验：研发项目文件夹管理 > 来源：Aligner 项目实践经验 > 最近核对：2026-06-01 > 适用范围：有输入材料、过程文档、源码、构建产物、QA 验收和长期知识沉淀的研发项目。 本文不是某个旧阶段的历史记录，而是从 Aligner 当前实际目录和构建方式中抽象出的通用项目文件夹经验。 结论：这套方式可以作为其他研发项目的通用模板，但应按项目规模和技术生态做少量裁剪；不要机械套到一次性脚本、纯开源库或已有严格 monorepo 规范的项目。 --- ## 核心理念 **项目根目录不是垃圾桶。** 一个项目如果根目录超过 10 个可见入口，通常说明输入材料、过程文档、源码、构建产物和知识沉淀已经混在一起，需要重新分类。 更准确的原则是： - 根目录只放导航和稳定入口。 - 输入、过程、产出分层。 - 源码、构建物、工具、长期知识各有唯一根目录。 - 当前包、旧包、研发中间产物不能混放。 - 构建脚本必须维护目录结构，不能只靠人手整理。 ## IPO 三层模型 通用根目录建议： ```text 项目根目录/ ├── 01-I/ 输入材料 Input ├── 02-P/ 过程材料 Process ├── 03-O/ 输出成果 Output ├── AGENTS.md Agent / 协作规则，可选 ├── DESIGN.md UI / 交互 / 视觉规则，可选 ├── GLOSSARY.md 术语表，可选 ├── INDEX.md 总索引 └── PROJECT.md 项目事实和边界 ``` 数字前缀的价值很实际：Finder、终端和 GitHub 都按字母序展示，`01/02/03` 能保证阅读顺序稳定。 ## 01-I：输入材料 `01-I/` 放外来的、原始的、需要研究的材料。它不是当前需求的事实源。 适合放： - 竞品截图、录屏、安装包、参考文档。 - 用户反馈原文、访谈记录、市场调研材料。 - 外部给来的需求草稿。 - 技术预研资料、第三方源码参考、实验样本。 不适合放： - 当前生效的 PRD / Round Spec。 - 当前源码。 - 当前构建产物。 - 已经沉淀为长期规则的项目知识。 Git 建议：默认不进主代码仓库。若公司要求材料留痕，应使用单独资料仓库或文档系统，不要把大图、大视频、竞品包塞进源码仓库。 ## 02-P：过程材料 `02-P/` 放执行过程中产生的材料，是会议、需求、任务、QA 和验收的工作区。 适合放： - Round 目录。 - PRD、研发规则、QA 计划、手测矩阵、用户验收记录。 - 会议纪要和会议产生的 todo。 - 统一 GTD，例如 Aligner 当前使用 `/Users/ar/Projects/Aligner/02-P/GTD.md`。 不适合放： - 源码。 - 可分发安装包。 - 已经稳定下来的长期业务知识和项目 SOP。 Git 建议：可以不进主代码仓库。对需要完整审计的团队，也可以把 `02-P` 放进文档仓库；但它仍然不应与源码、构建产物混在同一层。 ## 03-O：输出成果 `03-O/` 放可以被研发团队长期维护和复用的产出。Aligner 当前把 `03-O/` 作为唯一 Git 仓库根目录。 推荐结构： ```text 03-O/ ├── C1.source/ 源码根 ├── C2.builds/ 构建输出根 ├── C3.tools/ 构建、打包、诊断、QA 工具 ├── K1.业务知识/ 产品、业务、领域、系统行为知识 ├── K2.项目管理/ SOP、流程、复盘、项目管理经验 └── README.md 03-O 目录说明 ``` 这里的 `03-O` 不应理解为“只放最终成品”。更准确地说，它是研发项目的**可维护输出区**：源码、工具、长期知识、当前发布包都在这里，但必须继续分根目录管理。 ## C1.source：唯一源码根 Aligner 当前实际方式： ```text 03-O/C1.source/ ├── Package.swift ├── Resources/ ├── Sources/ └── Tests/ ``` 规则： - SwiftPM / Xcode 工程根是 `C1.source/`，不是项目根，也不是 `03-O/` 根。 - 源码、测试、资源放在 `C1.source/` 内。 - 构建缓存如 `.build/` 不应作为项目知识或交付物。 通用化时可以替换为对应生态的源码根，例如 `apps/`、`packages/`、`src/`。但原则不变：源码根只能有一个，不能让 `Sources/`、`Tests/`、`Package.swift` 散在项目总根目录。 ## C2.builds：构建输出根 Aligner 当前实际方式： ```text 03-O/C2.builds/ ├── --build/ │ ├── --build.dmg │ └── SHA256SUMS.txt ├── X-旧版build成果/ └── Z-研发中间产物/ ├── current/ │ └── .app ├── icon-work/ ├── locks/ ├── qa-reports/ └── tmp/ ``` 规则： - `C2.builds/` 根目录只保留三类入口：当前最新包目录、`X-旧版build成果/`、`Z-研发中间产物/`。 - 当前包必须单独成目录，目录名带产品名、版本号和 build 号。 - 当前包目录内放可分发包和校验文件，例如 `.dmg` 与 `SHA256SUMS.txt`。 - 旧包进入 `X-旧版build成果/`。 - 研发和 QA 过程文件进入 `Z-研发中间产物/`，例如当前可运行 `.app`、QA JSON、trace、截图样本、锁文件和临时文件。 - 旧 `.app` 默认不归档。macOS 会把多个旧 App 识别成不同候选，容易干扰权限、Spotlight、启动和 QA 判断。 - 可分发包重新打包时应递增 build 号；本地 QA 重复打包如未改 build，只能视为内部验证包，不应对外分发。 脚本责任： - 打包脚本必须自动维护这个结构。 - 打包结束后应断言 `C2.builds/` 根目录没有散落 `.app`、`.dmg`、JSON、trace、锁文件或临时文件。 - QA 脚本应默认读写 `Z-研发中间产物/`，不能污染根目录。 Git 建议：是否把 `.dmg` 等大二进制提交进 Git 要单独裁决。一般研发项目更推荐提交脚本、清单、版本记录和校验值，把大包交给 Release 系统或文件存储；如果项目早期为了本地协作把包留在目录里，也必须保持上述结构。 ## C3.tools：工具根 `C3.tools/` 放团队可复用的工程工具。 适合放： - 构建和打包脚本。 - QA 自动化脚本。 - 诊断脚本。 - 一次性但可复现的辅助工具。 不适合放： - 工具运行后产生的大量报告。 - 临时下载包。 - 当前 App 或安装包。 工具输出应进入 `C2.builds/Z-研发中间产物/` 或 `/tmp`，不能写回 `C3.tools/`。 ## K1 / K2：长期知识根 `K1.业务知识/` 放产品和领域知识，例如窗口行为、Space 排序、AX API、业务规则、设计决策。 `K2.非业务知识-项目管理/` 放非业务之外的其他只是，主要是项目管理知识，例如交付流程、代码审核流程、文件夹管理经验、协作规范、复盘。 两者都应进入长期版本管理。原因很简单：源码会变，过程文档会过期，但长期知识是后续研发效率的杠杆。 注意： - 业务知识和非业务知识不要混在一起。 - 已废除的旧流程必须在文件头明确标记 `X-已废除` 或移动到归档区。 - 新经验如果能复用到其他项目，应从当前项目细节里抽象出来，再写进 `K2.项目管理/`。 ## Round 和会议命名 Round 目录建议： ```text 02-P/RoundNN-<关键词>/ ``` 示例： - `Round00-Foundation` - `Round01-QuickSwitch-MVP` 会议目录建议： ```text YY.MMDD会议N ``` 示例： - `26.0529会议1` 这样做的好处是：时间顺序、轮次顺序和主题都能在 Finder 里自然排序。 ## X / Z 前缀约定 `X-` 表示归档、废除、旧版、历史参考。看到 `X-`，默认不能作为当前规则直接执行。 `Z-` 表示研发内部、低优先级展示、中间产物。看到 `Z-`，默认不是给用户或外部协作者看的正式成果。 这个约定很适合放在构建产物和历史材料里，但不要滥用到每个目录，否则会变成新的噪声。 ## 适用性判断 这套方式适合： | 项目类型 | 判断 | | ----------------------------------- | ---------------------------------- | | AI Agent 深度参与的研发项目 | 推荐，目录职责清楚能显著减少误读和误改 | | 有大量原始输入和过程会议的项目 | 推荐，`01-I` 与 `02-P` 很有价值 | | macOS / iOS / 桌面 App / SaaS 等持续迭代项目 | 推荐，构建产物和 QA 证据需要独立管理 | | 小团队 2-8 人项目 | 推荐，足够清晰但不重 | | 大团队 monorepo | 可借鉴，但应放到某个 product 子树内，不要覆盖公司既有规范 | | 开源库 / SDK | 谨慎，生态通常期待源码和 package manifest 在仓库根 | | 一次性脚本或极小实验 | 不建议，目录结构成本大于收益 | ## 落地检查清单 给新项目套用这套经验时，至少检查： - 根目录是否只有少数稳定入口。 - `01-I` 是否只放输入和参考，不承载当前规则。 - `02-P` 是否有统一 GTD 或任务入口。 - 当前 Round 的 PRD、研发规则、QA、用户验收是否有固定位置。 - `03-O` 是否是唯一代码仓库根，或至少有清楚的源码仓库根。 - 源码根是否唯一。 - 构建产物根是否唯一。 - 当前包是否只有一个最新目录。 - 旧包是否都进 `X-旧版build成果/`。 - QA 报告、trace、临时文件是否都进 `Z-研发中间产物/`。 - 打包脚本是否能自动维护目录结构，而不是靠人整理。 - 大二进制是否有明确 Git / Release 存储策略。 ## 对 Aligner 当前方式的判断 Aligner 当前文件夹管理方式整体是成立的，并且具备通用化价值。 最值得保留为通用经验的是： - `01-I / 02-P / 03-O` 分层。 - `03-O/C1.source` 作为唯一源码根。 - `03-O/C2.builds` 作为唯一构建输出根。 - `C2.builds` 根目录只保留当前包、旧版归档、研发中间产物。 - `03-O/C3.tools` 统一收纳构建、打包、QA 和诊断脚本。 - `K1 / K2` 区分业务知识和项目管理知识。 - `02-P/GTD.md` 作为过程 todo 的唯一扎口。 需要避免机械照搬的是： - `C1/C2/C3` 命名可以复用，但不同语言生态可能需要调整源码根名称。 - `.dmg` 是否进 Git 不能一概而论，应按团队的 Release 策略决定。 - 小项目不要为了形式强行建满所有目录。