# {{PRODUCT}} context-repo 导航

本仓库存放 {{DESCRIPTION}} 从需求立项到上线的全过程中间产物。

> 本文件是目录约定的真源，`CLAUDE.md` 软链指向它。改约定改这里。

**本地文件恒为唯一真源。** 阶段、影响范围、模块归属一律读文件算出，仓内不存同步状态。

## 目录约定

### prds/ — 产品需求层

PRD 是产品意图的唯一源，供多个 Jira 引用。

**功能模块：**

{{MODULES}}

{{PRD_STRUCTURE}}

### requirements/ — 开发层

按 Jira 组织，引用 PRD。

**Jira 实体结构：** `requirements/<JIRA-id>/`

- `manifest.yaml` — repos[]、prd.ref、refs[]
- `tech-spec/` — 技术方案（六阶段过程产物 + 子 manifest）
- `task-breakdown/` — 任务拆分清单
- `plan/` — 实现计划
- `retro/` — 复盘报告
- `test-runs/` — 测试执行记录

**逻辑代码仓 id**（manifest 只写 id，地址由 `~/.sdlc/config.yaml` 解析）：

{{REPOS}}

### assets/ — 共享资产层

跨 Jira 复用的 curated 契约，由 `extracting-assets` 提取。

**资产实体结构：** `assets/<asset-id>/`

- `manifest.yaml` — kind:asset + type + title + source[]（来源血缘，不自动跟）
- `contract.md` — 裁改后的稳定契约正文
- `touched-by.md` — 谁提取 / 谁消费 / 谁改过（append-only）

## 归属原则

产品意图、用例定义、需求粒度评估归 **PRD**；技术方案、任务拆分、测试执行归 **Jira**；跨 Jira 复用的接口、表、组件契约提取后归 **assets/**，来源 Jira 只留血缘。一句话：定义在 PRD、执行在 Jira、复用上升到 assets。

## kind → 落点速查

{{KIND_TABLE}}

本表供人查阅。**落位路径向 `sdlc-cli ctx resolve --kind <kind>` 要，不可字面拼接**——路由表由 CLI 持有，新增 kind 时本表可能滞后。

## 引用写法

- PRD：`prds/{{PRD_REF_EXAMPLE}}`，**不含模块段**。模块归属由目录位置决定，换模块只需 `git mv`，零引用改动。代价是 PRD id 须全仓唯一，由 CLI 强制。
- Jira：`requirements/<JIRA-id>`
- Asset：`assets/<id>`

## 模块与 PRD 的判据

`prds/` 下**有 `manifest.yaml` 的目录是 PRD 实体，没有的是模块分组目录**。深度上限一层。这条判据让扫描不会误入 PRD 内部的 `prd/`、`test-cases/`。

## 写入约定

skill 只做三步：读 → 写产物（贴 kind 标签）→ `sdlc-cli ctx commit <entity>`。

- 一次 run = 一次 commit，git 提供事务与回滚
- `ctx commit` 只校验 `manifest.yaml` 结构，`.md` 正文不校验
- commit 后默认 push（首次推送自动新建远程分支）；只留本地加 `--local`。推送失败只是 warning（`PUSH_FAILED` / `PUSH_SKIPPED`），提交仍然成立，别重跑 commit
- 发现 PRD 缺口别改 `prd/` 正文：往同 PRD 的 `feedback/` 追加 `FB-*.md`，随当前 Jira 的 commit 一起提交

## 常用命令

```bash
sdlc-cli ws init --product {{PRODUCT}}        # 建产品工作区（持久，一次即可）
sdlc-cli ws create --jira <id>                # 建开发工作区（随 Jira 生死）
sdlc-cli ctx modules                          # 列已有功能模块
sdlc-cli ctx scaffold <PRD-id> --module <名>  # 建 PRD 骨架（模块归属必答）
sdlc-cli ctx resolve --kind <kind> --jira <id>  # 要落位路径
sdlc-cli ctx commit <entity> -m "<说明>"      # 事务提交（默认提交后 push；--local 只留本地）
sdlc-cli ctx status <jira>                     # 当前阶段（读文件算出）
sdlc-cli ctx impact --prd <PRD-id>            # PRD 变更影响扇出
```