Project Arch

---
name: project-arch
description: 读取 project-prd 落盘的 CONTEXT.md 与 PRD，调研 GitHub 可复用方案，按官方文档确定技术栈与架构（已有项目则做增量影响分析），再调用 repo-init 规范仓库。用于技术选型、模块与接口设计和仓库初始化；实施计划交给 project-plan。
---

# 系统架构与工程初始化

流程：读取需求 → 调研可复用项目 → 设计架构 → 调用 repo-init。交付物：`docs/reuse-research.md`、`docs/architecture.md`、项目 `AGENTS.md`。需求范围由 project-prd 负责，业务代码由 task-implement 负责，实施计划由 project-plan 负责。用户已经提供架构文档时，核对覆盖情况后复用，不机械重做。

## 输入

- 读取 [开发流程契约](../shared/workflow-contract.md)、`CONTEXT.md`、需求文档和已有的项目规则。缺少需求文档时，提示用户先执行 [project-prd](../project-prd/SKILL.md)，不要臆测需求。
- 继承 PRD 的三级边界、能力地图和已有的代决策授权，不重做需求访谈。
- 已有文档沿用原位置，没有约定时写入上面列出的默认位置。

**已有项目的增量需求**：读取变更后的需求、当前架构和代码基线，只分析受影响的模块、接口、数据和依赖，在原架构文档中原地更新并标注版本；没有新的复用需求时，跳过调研。

## 调研可复用项目

- 根据已确认的需求和关键能力组织检索词，必要时同时用中文和英文。技术栈确定之前，不要先用自己偏好的语言或框架排除候选。
- 使用可用的 GitHub 连接器、`gh` 或网页检索。检索范围与项目规模相称：先筛出最相关的候选，再看 README、文档、LICENSE、Releases，必要时看 Issues 或源码。Star 数和搜索摘要只能作为线索。
- 对有价值的候选，记录以下内容：
  - 覆盖了哪些需求、还缺什么，复用方式是直接用、二次开发、组件集成还是仅作参考；
  - 与环境、数据和接口约束是否兼容，接入成本多高，能节省多少工作；
  - 许可证是否允许预期的用法（没有明确许可证的不能视为可复用）；
  - 维护状态和已知问题。
- 写入调研记录：检索日期、检索词、候选对比、证据链接、推荐方向和缺口。只读过文档或源码的，标为“文档/源码核查”，不能写成已验证。没找到合适的候选时，写“本次未找到”，不要断言不存在。
- 不为了调研而克隆、安装或运行第三方代码。确需验证时，先说明要验证的具体疑点。
- 已有调研记录时只补缺口。用户明确要求跳过时，记录这一决定。GitHub 无法访问时，记录调研未完成，可以继续写架构草稿，但未核查的候选不能定为已采用方案。

先向用户展示调研结论，然后进入架构讨论。

## 设计架构

- 给出适合项目规模和约束的推荐方案，说明关键选择和代价。只在确实存在取舍时才比较替代方案，不默认引入复杂的基础设施。
- 技术栈和依赖按 [source-driven-development](../agent-skills/build/source-driven-development/SKILL.md) 用官方文档或最新脚手架核实，避免使用已废弃的 API。
- 架构文档按适用性包含：
  - 技术栈、运行与部署方式，以及选型理由；
  - 复用决策（引用调研记录），包括复用边界、上游版本，以及需要自己开发的部分；
  - 模块职责、依赖方向、主要接口、数据流，需要持久化时说明数据组织；模块和接缝按 [codebase-design](../mattpocock/codebase-design/SKILL.md) 设计成深模块，用它的术语；
  - 计划的目录结构，以及代码、测试、配置、文档分别放在哪里；
  - 生成物、日志、缓存的位置，已有版本机制时的版本来源；
  - 与需求验收对应的验证方式，以及待定事项。
- 只与用户讨论确实需要他们决定的问题。已确认或已授权由你决定的事项，不重复确认。关键决策还没解决时，架构保持草稿状态。满足 ADR 门槛的选型写入 `docs/adr/`。
- 尚未实现的目录、工具和命令标为“计划”。已有架构文档时只更新受影响的部分，保留用户手写的内容；发现更合适的方案时说明影响，不擅自推翻用户已确认的架构。

## 调用 repo-init

- 需求和架构就绪、没有阻塞性决策后，执行 [repo-init](../repo-init/SKILL.md)。交给它：项目路径、`CONTEXT.md`、需求和架构文档的位置、调研记录与复用决策、当前文件状态、目标 Agent（未指定时说明未指定），以及本次新建的文件和临时输出位置。
- repo-init 完成后，检查 `AGENTS.md` 是否引用了术语、需求和架构文档，目录约定是否与架构一致。
- repo-init 不可用时，保留已完成的文档，说明剩余步骤，不要自己仿写一套替代流程。

## 交付

- 核对：术语、需求、调研、架构、`AGENTS.md` 彼此一致，引用都能访问，候选与已采用、计划与现状都已区分。
- 交付时列出文档链接和待定事项。已授权实施计划或完整开发时，交给 [project-plan](../project-plan/SKILL.md)，并转交已有的授权。
- 作为顶层任务执行时，最后执行 [task-closeout](../task-closeout/SKILL.md)。只为本次产物做适用步骤：不为目录规划创建空目录，也不为纯文档初始化强制创建版本文件或 README。