Jellyfish / rules

---
description: Jellyfish 文档目录职责与更新治理规则
alwaysApply: true
---

# Jellyfish Documentation Governance Rules

## 目录职责

- `site/content/blog` 用于存放 release note。
- 未被明确指定时，不修改已固化版本的 release note。
- `site/content/docs` 栏目职责必须严格区分：
  - `guide` = 开发指南 / how-to，回答“怎么做”。
  - `architecture` = 当前架构，回答“现在是什么”。
  - `plans` = 任务计划，回答“接下来做什么”。
  - `reference` = 稳定参考资料，回答“查什么”。

## 文档归属判定

- 新增或调整文档前，必须先判断内容归属：
  - 当前真实实现、当前边界、当前状态流转 -> `architecture`
  - 正在推进或待推进的改造方案、任务拆解、阶段计划 -> `plans`
  - 操作说明、开发流程、接入方式 -> `guide`

## 协作约定

- 涉及系统结构、状态语义、页面职责边界调整时，必须同步更新 `site` 文档：
  - 当前已生效规则，更新到 `site/content/docs/architecture/`
  - 尚在推进中的方案，更新到 `site/content/docs/plans/`
- `architecture` 与 `plans` 必须保持动态更新，不允许长期滞后于真实代码状态：
  - 架构已落地但文档未更新，视为未完成。
  - 计划已变更但文档未更新，视为未完成。

## 文档更新原则

- `architecture` 文档：
  - 只记录当前真实生效的实现。
  - 不混入“未来准备怎么改”的内容。
  - 当代码行为、状态语义、页面职责发生变化时，必须同步修订。
- `plans` 文档：
  - 记录当前仍在推进中的计划、分阶段任务和方案。
  - 当计划范围、优先级、执行路径发生变化时，必须同步修订。
  - 某项计划稳定落地后，应沉淀到 `architecture` 或发布到 `blog`。
- 同一主题若同时涉及“当前事实”和“未来计划”：
  - 当前事实写入 `architecture`
  - 未来执行写入 `plans`
  - 不得混写在同一篇 how-to 中

## Release Note 规范（site/content/blog）

- release note 必须采用稳定结构（可按需裁剪，但顺序不变）：
  - `Highlights`
  - `Added` / `Changed` / `Fixed`
  - `Breaking Changes`（存在行为/契约变化时必填）
  - `Deprecations`（存在弃用路径时必填）
  - `Security`
  - `Known Issues`
  - `Migration Guide`
  - `Rollback Notes`
  - `Compatibility Matrix`
  - `Validation Commands`
  - `Upgrade Checklist`
  - `References`
  - `Notes for Contributors`
  - `Acknowledgements`
- frontmatter 最低要求：
  - `title`
  - `date`
  - `description`
  - `tags`
  - `authors`
- 写作风格要求：
  - 使用维护者发布口径，优先“变更结论 + 升级动作 + 风险提示”。
  - 术语保持一致，不混用状态语义（如 `shot.status` 与 runtime task status）。
  - 升级、回滚、验证信息必须具备可执行性，避免模糊指引。
  - 采用清单化与短段落表达，避免重复叙述与无信息密度段落。

More agent context in Forget-C/Jellyfish

5 other files this repository gives its agents.