人機協作文件六層架構與單向 Sync Pipeline

Context

yibi-mvp 的文件散落在多處（Confluence、Jira、GitHub docs/features/ + docs/openspec/、Figma），不同角色（PM、Designer、RD、AI）在各自工具工作，沒有清楚的「source of truth 分層」，導致：

同一 feature 的 PRD 內容在 Confluence + Jira + proposal.md + spec.md 各有一份
Figma 設計改動無法自動同步到 spec
bug fix 與 refactor 的決策沒有跨 PR 可查的記錄
docs/features/ 與 docs/openspec/specs/ 雙軌並行，不知道以哪個為準

Decision

結論：採用六層文件架構，每層綁定單一 owner，並建立單向 Sync Pipeline。

六層架構

Layer	主場	Owner	工具
L1a PRODUCT	Confluence + Jira	PM	Atlassian MCP（live 查詢，無 repo mirror）
L1b DESIGN	Figma（Ready for Dev 標記）	Designer	`/design-ready`
L2 SPEC	`docs/openspec/`	RD + AI	`/spectra-*`
L3 DECISION	`docs/adr/`	Tech Lead + RD	`/adr`
L3.5 EXPLORATION	`docs/research/` + `docs/poc/`	RD + Tech Lead	（慣例）
L4 ARCHITECTURE	`docs/architecture/`	Tech Lead	`/architecture`
L5 AGENT	`.claude/rules/` + `CLAUDE.md`	全工程師	（不動）

單向 Sync 原則

Confluence PRD → (Atlassian MCP live 查詢；不留 repo mirror) → intake-summary → proposal/spec
Figma Ready for Dev → docs/design/snapshots/ → design-ready report → Jira/Slack
openspec changes → Jira comment (不覆蓋 PM Description)
change archive → docs/adr/ ADR
/pr-retro lesson → docs/adr/ ADR

修訂（change 0030-drop-prd-mirror）：原 L1a docs/product/prds/ PRD mirror + /prd-sync 因實務上只同步過一次即停擺、形同虛設而廢除。PRD 改以 Confluence/Jira 為單一真相，需要時以 Atlassian MCP live 查詢。本 ADR 仍 status: proposed，此修訂依使用者決策實作，正式 accept 待 Tech Lead 確認。

每一步單向，下游改動留 marker 通知上游，不寫回。

openspec change 命名規則

NNNN-<kebab-name>/（4 位流水序號，按首次提交時間），各與 ADR 編號獨立。

docs/features/ 漸進取代

docs/features/<X>/E0X-*.md 的 PRD 性質內容歸 Confluence（L1a 單一真相，無 repo mirror，見 change 0030-drop-prd-mirror）；spec 部分對齊 docs/openspec/specs/。邊用邊搬，不批次。

docs/features/ 已凍結為唯讀；migration 逐項追蹤表與退場條件見 docs/features/README.md。硬性 sunset 日期與最終刪除動作待 Tech Lead 確認。

Alternatives Considered

雙向 sync（Confluence ↔ openspec） — 考慮過。Webhook 實作複雜，PM/RD 各自修改衝突解析規則難定義，現有 spectra-jira-sync 刻意只做單向也印證此方向。
全部移到 GitHub Markdown（廢棄 Confluence） — 考慮過。PM 學習成本是文化問題不是工具問題，強制 migrate 風險高。
只做命名規則，不加 product/decisions 層 — 考慮過。不解決「微決策無家」與「PRD mirror 不存在」的根本問題。

Consequences

好：

每個角色只在自己熟悉的工具工作（PM 在 Confluence、Designer 在 Figma、RD 在 GitHub）
ADR 四條進入路徑讓 bug fix、refactor、design 取捨都能被記錄
AI agent 有單一進入點（L2 SPEC + L3 DECISION）不需拼湊多個系統

壞 / 代償：

docs/features/ 漸進 migrate 需要長期維護過渡期（2-3 個月）
四個新 skill（prd-sync、design-ready、adr、architecture）需要時間實作
Figma Ready for Dev workflow 需要 Vivian/Marcel 採用（人的因素）

中性：

.claude/rules/ + path-scoped CLAUDE.md 不動（已是好設計）
archived openspec changes 不溯及加編號（避免破壞既有 Jira comment 引用）

人機協作文件六層架構與單向 Sync Pipeline

On this page