Imported from chialecode/manga (AGENTS.md). Install upstream with npx skills add chialecode/manga. Copyright stays with the author.

MANGA 仓库：Agent 工作入口

本文件是 Codex、Claude Code 及其他 AI 编码助手共用的项目指令正本。 CLAUDE.md 只保留 @AGENTS.md，不要在两处重复维护规则——重复的规则一定会先不一致，再失效。

本文是行为约定与规则索引，不是规则正文。每条约定都注明了权威来源；两者冲突时以权威来源为准。 人类协作者请看 CONTRIBUTING.md。

仓库边界

• 本仓库包含 MANGA 的全部内容：产品定义、技术架构、执行计划、文档治理框架， 以及 apps/desktop 与 packages/* 下的应用代码。
• 开始工作前先确认当前分支、工作区状态与相关源码，不覆盖、不回退用户已有改动。
• 本仓库是单人项目。单人不意味着可以省掉流程——恰恰相反，没有第二个人兜底时， 自动检查就是唯一的评审者。

README.md            项目入口
CONTRIBUTING.md      协作上手路径
AGENTS.md            本文件：AI 助手的规则索引
REVIEW.md            代码评审口径（自评与自动评审共用）
SUPPORT.md           使用支持与提问分流
DCO                  Developer Certificate of Origin 1.1 全文
docs/README.md       全部文档的唯一索引（生成产物）
docs/product/        产品需求（上游）
docs/architecture/   架构方案 + ADR-001~027 正文
docs/decisions/      ADR-028 起的独立决策记录
docs/plans/          阶段执行计划、前置准备清单、偏差日志
docs/dev-rules/      有约束力的规则
docs/ops/            可执行运维手册
docs/templates/      文档模板
apps/desktop/        桌面应用
packages/*           内核、运行时、存储、协议、UI 等 workspace 包
tools/*              依赖规则、ESLint 配置、fixtures、tsconfig
spikes/s-*/          技术验证及其结论
scripts/docs/        文档检查工具链（零运行时依赖）
legacy/              冻结区：只读参考存档，不编译、不 import、不修改
.githooks/           DCO 签名 hook（需手动安装）
.github/             CODEOWNERS、PR/Issue 模板、workflows、ruleset 定义

规则组织

• 有约束力的规则统一放在 docs/dev-rules/。判断标准：违反它应当导致 PR 被拒绝或 CI 失败。
• 可执行的操作步骤放在 docs/ops/，只给步骤，不重复规则条文。
• 产品行为以 docs/product/product-requirements.md 为上游，架构形态以 docs/architecture/ 为准。
• 本文只保留所有任务都适用的约定、触发条件与索引；专题细则不在这里展开。
• 只是"建议这样做"的内容不进 docs/dev-rules/——空规则比没有规则更糟， 它会让人以为规则已经存在而不去检查。

当前规则索引

按触发条件读，不要通读：

• 改动 docs/ 下任何文件前，必须先读 文档治理规范： 七个必填 front matter 字段、分类归属边界、生命周期与权威来源标注。
• 提交、开 PR、或任何涉及分支与合并的操作前，必须先读 Git 与 PR 工作流，特别是 §3.1 本地 CI 优先 与 §7 AI 代理的写操作边界。
• 需要动 Ruleset、CI 配置、仓库设置或恢复仓库协作配置前，必须先读 仓库运维手册。不要在 GitHub UI 上改了却不回写 .github/rulesets/main.json——那会让仓库里的定义变成谎言。
• 改动会影响产品范围、用户可见行为或功能边界时，必须先读 产品需求文档，并确认是否需要一条 ADR。
• 改动架构形态（模块边界、协议、数据模型、插件契约）前，必须先读对应的 架构文档。协议类改动（架构文档 03/04/05 中的类型定义） 一律视为破坏性变更。
• 做技术选择、或改变一个已经做过的技术选择前，先查 决策记录。 决策不允许只存在于对话或 Issue 里——Issue 会被搜索淹没，ADR 不会。
• review 代码或自查 diff 前，读 REVIEW.md 的审阅口径， 尤其是「不要重复机器门禁」一节。
• 动 scripts/docs/ 下的检查规则前，必须在 PR 描述里单独说明理由，并同步更新 文档治理规范。 不要为了让检查通过而放宽检查规则。
• 读到 legacy/ 下的代码时，它是只读参考存档：不编译、不 import、不修改。 用途与删除条件见该目录下的 README.md。重写对应能力时可以对照抄， 但不得把冻结区接进 workspace、不得从主干 import。
• 需要引用别处已经写过的内容时，给相对路径链接，不要复述。确需在别处复述， 把该文档标为 authority: "reference" 并填 source_of_truth。

通用工作流程

1. 先确认用户目标、当前分支、工作区状态。
2. 尊重用户已经提供的 Git 工作流。已有任务分支时直接复用，不嵌套创建； 不要擅自搬动或混用现有工作区。
3. 按上面的索引读取相关规则——按触发条件读，不要通读。
4. 先读实际代码和测试，再决定实现；不要只依赖文档猜测现状。
5. 修改时保持范围最小，保护用户已有改动，不使用破坏性 Git 命令。
6. 完成后运行与风险匹配的检查，并从头 review 整体 diff。
7. 如实报告已验证、未验证、风险和需要用户决定的事项。

每次改动后必须执行

pnpm docs:index   # 改动 docs/ 下任何文件的 front matter 或增删文档后
pnpm docs:check   # 提交前，必须四项全绿

涉及代码时追加：

pnpm lint && pnpm typecheck && pnpm dep:check && pnpm test
pnpm check:dco    # 校验本次提交范围的 DCO 签名

不要在检查失败的情况下提交。 检查项与 CI 完全一致，本地绿 = CI 绿。 不得通过跳过、删除或弱化测试制造通过。

写文档时

• 从 模板 复制，七个必填 front matter 字段一个都不能少。
• title 必须与正文第一个 H1 逐字一致，改标题要同时改两处。
• front matter 的值必须是合法 JSON 字符串或字符串数组（这是解析器的硬要求，不是风格偏好）。
• 中文为主，技术名词保留英文，中英文之间加空格。
• 结论先行：先结论，再理由，最后备选方案与代价。
• 不要手工编辑 docs/README.md 中 <!-- docs-index:start --> 与 <!-- docs-index:end --> 之间的内容。 那是生成产物，用 pnpm docs:index 重建。
• 不要在 docs/ 下新建未登记的一级目录。 需要新分类时，先在 scripts/docs/lib/docs.mjs 的 SECTIONS / SECTION_TYPES 登记，并在 文档索引 §1 补上边界说明。
• 不要删除文档。 退役用 status: "deprecated" 或 "superseded"，保留文件。 ADR 编号只增不改、不复用。
• 不要修改已 Accepted 的 ADR 正文。 改变主意时新增一条并标注 supersedes。
• 不要把未验证的结论写成确定结论。 标注 ⚠ 待验证，并在 07 · 技术风险与验证计划 登记 Spike。

Git 与交付

• 本仓 PR-first：所有改动走分支 + PR 进入 main。main 禁止直接推送， Ruleset 无 bypass 名单，仓库管理员同样不能直推。
• 提交信息用 Conventional Commits，分支名 <type>/<slug>。
• 每个提交都要带 DCO 签名：git commit -s。一次配好可跑 pnpm dco:install-hook 安装 .githooks/prepare-commit-msg。 提交前自查 pnpm check:dco；门禁是 PR 上的 DCO 检查（官方 DCO App，见 ADR-032），本地脚本只是自查。 DCO 全文见根目录 DCO。
• 不要用推送来试错。 本地跑绿再推，一个阶段推一次。同一个 PR 上远端 CI 连续失败两次就停下来，在本地复现问题，不要靠反复推送逼出答案。
• 一个 PR 只做一件事；文件搬家与内容修改必须拆成两个 PR。 "一件事"约束主题，不约束提交数量：一个阶段内的多个任务属于同一件事，攒在一个 PR 里推。
• 提 PR 时按 PR 模板 如实说明改动、验证与风险。 写"已测试"而不写实际执行的命令与结果，等于没写。

绝对安全底线

这一节没有例外条款。拿不准时停下来问，不要自行判断。

• 未经用户在本次对话中明确授权，不执行 push、合并 PR、打 ready-to-merge 标签、 发布、删除分支、改写历史、删除数据等对外或难以恢复的操作。 上一次的授权不延续到下一次；任务描述里隐含的推断不算授权。

• AI 代理在任何情况下都不得合并 PR。 具体包括：不得运行 gh pr merge、 不得通过 API 触发合并、不得在 GitHub UI 上合并、不得给 PR 打 ready-to-merge 标签。 合并授权属于仓库负责人，见 CODEOWNERS。

  这条不看 diff 大小，不看检查是否全绿，也不因为「用户让我完成这个任务」而豁免—— 完成任务不等于授权合并。把 PR 开好、检查跑绿、说明写清楚，就是任务的终点。

  服务端拦不住这件事：GitHub 无法区分「仓库负责人本人」和「持有其凭证运行的 AI 代理」。 merge-authorization 检查提供的是显式性与可追溯性，不是强制隔离。 这条禁令的约束力来自这里，而不是来自那个检查。

• 用户凭证、令牌、授权文件和密钥不得写入仓库或任何可能被 Git 跟踪的路径。 已经提交的凭证，轮换是第一步——从 Git 历史里删除并不能使其恢复安全。

• 发现任务会触及产品范围、架构形态、安全边界、用户数据或协议兼容时， 必须先停下来核对专项规则，并在动手前向用户说明风险或请求确认。 这类判断属于 CODEOWNERS 中的负责人。