项目、仓库与 GitHub Projects

项目是用户成果和维护责任的逻辑边界；Git 仓库是代码与历史的边界；GitHub Project 是规划和状态视图。三者不需要一一对应。

实体和权威位置

实体	责任
项目组合	项目目录、优先级和共用工程标准。
逻辑项目/产品	用户成果、范围、生命周期和负责人；可以有多个代码仓库与多个看板。
组件、服务或 SDK	某项能力及其接口；可以独立部署，也可以与别的组件同仓库。
仓库	源码历史、仓库级文档、代码评审和 CI；应有明确维护责任。
GitHub Project	收纳任务并提供表格、看板、路线图等视图；明确其用途和状态权威。
clone 或 worktree	同一仓库的一份本地工作位置，不是新项目。

每个逻辑项目应有稳定的 project_id，不依赖本地路径、GitHub 账号、仓库名称或看板编号。共享仓库须指明一个负责方和它服务的消费者。

一个项目可以多个仓库和看板

例如，一个产品可以有核心服务、Web 控制台、Go SDK 和文档站等仓库。若任务需要跨仓库协调，可设“产品交付”Project；长期方向、里程碑与跨产品投资可另设“产品路线图”Project。两者任务范围、受众、节奏和状态用途不同，才值得分开。

一个 Project 可以汇总多个仓库中的 Issues 和 PR；多个 Project 也可以承载同一个逻辑产品的不同规划目的。每项任务只保留一个交付状态权威。Project 专有的自定义字段不会自动跨 Project 同步；除非配置并验证自动化，否则不要承诺同步。

仓库边界

当组件通常一起变更、共享维护者和访问权限，并受益于原子改动及一致的构建时，优先同仓库。若有独立消费者/发布周期、访问边界、外部贡献者、维护责任或显著不同生命周期，可拆分仓库。前后端天然不需要分仓；多个可部署组件也可以位于单体仓库。多个仓库不等于微服务。

拆分、合并或改名之前，盘点模块导入、包名、镜像名、子模块、CI、GitOps、文档链接、发行版本和下游使用者，并写明兼容期及回退策略。仓库名相似、目录相邻或使用更新语言都不是合并或继承关系的证据。

文档所有权和项目地图

选一个现有仓库作为协调仓库，优先复用主仓库。它拥有产品范围、跨仓库架构、项目地图和集成计划；成员仓库各自拥有实现、运行命令、公开契约、数据迁移和运维手册。文档站可以保留为既有权威位置。

项目地图至少记录 project_id、负责人或待定、生命周期、协调仓库、成员仓库的稳定键与角色、文档入口，以及每个 Project 的目的和交付状态权威。私有的本地绝对路径、凭据和机器映射应与可分享的项目地图分开。生成的仓库清单、分支和 dirty 状态只是带时间的观察快照，不能覆盖负责人确认的关系。

轻量本地工作区

workspace/
  projects/
    sample-platform/
      repos/
        sample-platform/          # Git 仓库和协调仓库
        sample-platform-web/      # 独立 Git 仓库
        sample-platform-sdk-go/   # 独立 Git 仓库
  workspace.local.json            # 仅本机使用，不能提交

上层目录可以是普通文件夹，不必再套一层 Git。新工作区可这样安排，但不得为整齐而搬动已有源码、活动 worktree 或含本地数据的目录。