agentic-dev-docs 是一个面向 Codex 的文档优先开发规划 skill。它不会直接替你开工写产品代码，而是先把项目想法、需求说明或开发任务整理成一套可以交给 Codex 新窗口执行的“主控开发控制包”。
这套控制包的目标是让后续开发过程更可控：先明确项目画像、阶段边界、权限矩阵、workstream 分工、Review 和审计规则，再由唯一的 A 主控智能体协调执行。
当前版本：0.6.4
GitHub 仓库：https://github.com/mayuri-wylty/agentic-dev-docs
当一个任务稍微复杂一点，直接让 AI “开始实现” 很容易出现几个问题：
- 主控会一边规划一边写代码，阶段边界混乱。
- 多个子任务同时推进时，谁能改哪些文件不清楚。
- Review、测试、进度记录和最终审计容易被省略。
- 人类文档里的 Developer A、QA、Tech Lead 等标签容易被误映射成错误的 agent 身份。
- A 主控为了“顺手”直接实现 workstream 的任务，导致权限矩阵失效。
- 长任务跨窗口执行时，新窗口缺少统一启动上下文。
agentic-dev-docs 的设计思路是：先把这些协作规则写成文档，再让开发执行窗口读取文档工作。
适合使用本 skill 的场景：
- 你有一个项目想法，需要先生成开发计划和协作文档。
- 你要把现有需求文档转换成 Codex 可执行的开发控制包。
- 你希望用一个 A 主控智能体协调多个 workstream。
- 你希望明确哪些角色只读，哪些角色可以写代码。
- 你希望新 Codex 窗口能通过启动提示词快速接管项目。
- 你希望结合 Codex
/goal模式追踪较长的开发执行目标。 - 你希望在 workstream、Review 和审计任务中记录推荐 reasoning effort。
- 你希望在作 plan 前显式指定全局 skill 或某类任务专用 skill。
不适合的场景：
- 只想问一个普通技术问题。
- 只想让 Codex 直接修一个很小的 bug。
- 只需要生成普通 README、注释或单页文档。
- 已经处在执行阶段，并且不想补充协作文档。
这是一个严格手动触发 skill。只有明确点名时才应该使用，例如：
$agentic-dev-docs
或：
use agentic-dev-docs skill
或：
请使用 agentic-dev-docs 为这个项目生成开发控制文档包
普通的“帮我规划一下”“帮我写代码”“帮我做文档”不应该自动触发它。
每个生成的开发控制包中只能有一个 A-main-control。
A 主控负责：
- 协调 workstream。
- 判断冲突和并行边界。
- 维护任务进度。
- 安排 Review。
- 安排进度一致性审计。
- 汇总证据并向用户报告。
A 主控不应该直接实现已经分派给 workstream 的产品代码任务。
Workstream 是按项目实际结构生成的工作流实例，不是固定的前端/后端/测试模板。
它可以按这些边界生成：
- 目录
- 模块
- 服务
- 页面
- 命令
- 数据域
- 文档章节
- 部署或配置范围
示例名称：
sdk-cli-workstream
admin-ui-workstream
storage-executor-workstream
data-schema-workstream
docs-revision-workstream
每个可写角色必须出现在权限矩阵中。矩阵至少要说明：
| 字段 | 含义 |
|---|---|
| Role / instance | 精确角色或实例名 |
| Type | A 主控、实现 workstream、Review、审计、文档等 |
| Default agent | 当前会话、worker、explorer 或逻辑实例 |
| Product-code write | 是否允许写产品代码 |
| Writable scope | 可写目录、文件类型、模块或文档范围 |
| Forbidden scope | 禁止触碰的范围 |
| Required evidence | 测试、构建、截图、日志、Review 或审计证据 |
| Recommended reasoning effort | 推荐思考程度：low、medium、high 或 xhigh |
| Skill routing | 用户显式指定的全局继承 skill 或任务专用 skill；未指定时留空 |
| Review owner | 负责 Review 的角色 |
| Close condition | 关闭任务的客观证明 |
不在权限矩阵中的角色不能修改产品代码。
本 skill 明确区分两个阶段。
当前阶段只做需求澄清、协作设计、计划生成和开发文档生成。
在这个阶段不要：
- 创建产品代码。
- 初始化项目脚手架。
- 安装依赖。
- 生成 migrations。
- 运行 dev server。
- 修改产品代码目录。
执行阶段从新窗口开始。用户复制 00_新窗口启动提示词.md 后，新的 Codex 窗口读取开发控制包，确认自己是唯一 A 主控，然后再推进开发。
如果使用 Codex /goal 模式，可以再复制同一文件中的 /goal 执行目标，让 Codex 长期追踪主控开发目标。
v0.6.4 强化真实子智能体的 reasoning effort 显式传递规则。
创建或派发真实子智能体时，A 主控不得默认让子智能体继承父会话思考程度。必须先读取权限矩阵中的 Recommended reasoning effort，并在任务说明或调用参数中显式传递或要求 reasoning_effort。
优先级固定为：
permission matrix recommended value -> parent session default -> documented exception with A-main-control confirmation
只有目标 workstream 没有配置推荐值时，才继承父会话默认 reasoning_effort，并在任务进度中记录 fallback。若因成本、速度或工具限制需要调整推荐值，必须先记录原因并获得 A 主控确认。
v0.6.3 增加显式 skill routing 策略。
用户可以在“现在开始作 plan”前用自然语言指定两层 skill：
- Global skill baseline：所有智能体继承，包括
A-main-control、真实子智能体和逻辑 workstream。 - Task / workstream skill routing：只作用于某类任务、某个 workstream、Review、审计或 one-shot assignment。
示例：
需求文档: D:/AL_Code/A1-CKY/docs/cky/项目工作日志-wly/浏览器反馈Bug修复需求-2026-06-04.md
文档输出目录: D:\AL_Code\A1-CKY\docs\cky\项目工作日志-wly\多智能体文档
所有智能体（包括主子）使用skill：caveman + karpathy-guidelines
执行前端测试任务的子智能体使用skill：playwright
现在开始作plan
生成 plan 和文档时，只有用户明确指定 skill 才记录 skill routing。如果用户没有指定 skill，保持默认行为，不推断、不发明、不强制加入任何 skill。
当存在 skill routing 时，plan、启动提示词、总控入口、协作规范、任务进度记录和文档验收清单需要记录：
- 全局 skill。
- 任务或 workstream 专用 skill。
- 派发任务时的触发语，例如
use playwright skill。 - required skill 不可用时的 fallback。
A 主控派发任务前必须合并全局 skill 和任务专用 skill，并在任务说明中显式写出 required skill 的触发语。
v0.6.2 增加 reasoning effort 策略。
生成 workstream registry、permission matrix 或任务分配时，需要记录推荐思考程度：
A-main-control默认high。- 最终裁决、跨 workstream 冲突、权限缺陷和最终审计使用
xhigh。 - 普通 implementation workstream 默认
medium。 - 简单查找、整理、格式化和低风险文档清理使用
low或medium。 - contract-review、security-review、progress-audit 和高风险 Review 使用
high。 - final closeout audit 使用
xhigh。
当真实 subagent 或调用接口支持 reasoning effort 时，A 主控必须在派发任务时设置或明确要求对应档位；若平台不支持直接设置，也必须把推荐档位作为执行约束记录在文档中。v0.6.4 起，真实子智能体优先按权限矩阵 Recommended reasoning effort 显式传递或要求 reasoning_effort，只有矩阵未配置推荐值时才继承父会话默认值。
v0.6.1 增加 Codex /goal 模式启动支持。
生成 00_新窗口启动提示词.md 时，文件中会包含两段可复制内容：
- 新窗口启动提示词。
- 独立的
/goal执行目标。
示例：
/goal 作为本项目唯一 A 主控智能体，按开发文档目录中的控制包完成主控开发执行：先完成启动前环境核验，读取总控入口、任务进度、协作规范和权限矩阵；创建或复用授权 workstream；协调实现、测试、Review 和进度一致性审计；最终向用户汇报证据、风险和人工测试结果。默认不要提交代码、不要推送代码，除非本项目 plan 或用户后续消息明确授权。
默认策略：
- 不提交代码。
- 不推送代码。
- 不创建 PR。
只有项目 plan 或用户后续消息明确授权时，才允许把提交、PR 或推送作为执行收尾步骤。
agentic-dev-docs 会根据项目复杂度选择最小、标准或完整文档集。
适合小脚本、小 CLI、单文件工具和低风险原型。
00_新窗口启动提示词.md
00_启动前环境核验.md
00_总控开发入口.md
01_需求规格说明.md
02_任务进度.md
03_多智能体开发协作规范.md
04_人工测试清单.md
05_文档验收清单.md
适合常规 Web、CLI、桌面应用和 AI 应用。
00_新窗口启动提示词.md
00_启动前环境核验.md
00_总控开发入口.md
01_项目总规划.md
02_需求规格说明.md
03_系统设计说明.md
04_接口契约规范.md
05_多智能体开发协作规范.md
06_A主控智能体工作规范.md
任务进度.md
开发日志规范.md
人工测试清单.md
文档验收清单.md
后续迭代路线图.md
每个被选中的 workstream 还会有自己的工作规范文档。
适合中大型、多端、多服务、高风险或长期维护项目。通常在标准文档集基础上增加：
前端设计说明.md
后端设计说明.md
数据与存储设计.md
外部服务接入规范.md
安全与隐私边界.md
部署与运行手册.md
回归测试计划.md
风险清单.md
把整个 agentic-dev-docs 目录放入 Codex skills 目录。
Windows 示例：
C:\Users\<你的用户名>\.codex\skills\agentic-dev-docs
如果你从 GitHub 克隆：
git clone https://github.com/mayuri-wylty/agentic-dev-docs.git C:\Users\<你的用户名>\.codex\skills\agentic-dev-docs然后在 Codex 中显式调用：
$agentic-dev-docs
agentic-dev-docs/
├─ SKILL.md
├─ README.md
├─ agents/
│ └─ openai.yaml
├─ assets/
│ └─ doc-templates/
│ ├─ 人工测试清单.template.md
│ ├─ 任务进度.template.md
│ ├─ 启动前环境核验.template.md
│ ├─ 多智能体开发协作规范.template.md
│ ├─ 总控开发入口.template.md
│ ├─ 接口契约规范.template.md
│ ├─ 文档验收清单.template.md
│ └─ 新窗口启动提示词.template.md
├─ references/
│ ├─ agent-roles.md
│ ├─ document-set.md
│ ├─ examples.md
│ ├─ templates.md
│ └─ workflow.md
└─ 更新内容.txt
在 Codex 中输入：
$agentic-dev-docs
然后描述你的项目或任务。
skill 会只询问会影响计划的关键问题，例如：
- 项目类型是什么？
- 主要交付物是什么？
- 技术栈是否已经确定？
- 是否需要真实多智能体并行？
- 哪些目录或模块可以并行开发？
- 是否允许最终提交、推送或创建 PR？
计划会包含：
- 项目摘要和项目画像。
- 已冻结的决策和假设。
- 文档集规模。
- 要创建的文档列表。
- Workstream 注册表。
- 复用策略。
- 权限矩阵。
- 推荐 reasoning effort。
- 显式 skill routing。仅当用户指定 skill 时生成；未指定时保持空白默认。
- 契约优先规则。
- 启动前环境核验。
- Review 和审计门禁。
- 验收标准。
- 人类责任标签到 workstream 或 Review owner 的映射。
用户确认计划后，skill 才生成或编辑开发文档。文档生成仍然不是产品实现。
打开新的 Codex 窗口，复制 00_新窗口启动提示词.md 中的新窗口启动提示词。
如果要使用 /goal 模式，再复制同一文件中的 /goal 执行目标。
/goal 目标适合长任务，因为它可以让新窗口持续记住顶层目标。
推荐顺序：
- 先复制新窗口启动提示词。
- 等 Codex 完成启动前环境核验。
- 再复制
/goal执行目标。 - 让 A 主控按任务进度、权限矩阵和 Review/审计门禁推进。
如果项目 plan 没有明确授权提交或推送，A 主控最终只汇报变更、证据和风险，不执行 git commit、git push 或 PR 创建。
- Exactly one
A-main-control。 - A 主控不直接实现已分派给 workstream 的产品代码任务。
- 产品代码、schema、OpenAPI、typed client、测试和部署脚本修改必须分配给授权 workstream 或逻辑 workstream。
- Review、审计和 explorer 默认只读，除非文档明确授权窄范围写入。
- 每个可写角色必须先进入权限矩阵，再接任务。
- 每个真实 subagent 或逻辑 workstream 都要记录推荐 reasoning effort；真实子智能体派发时必须优先按权限矩阵显式传递或要求
reasoning_effort。 - 用户指定 skill 时，A 主控必须合并全局 skill 和任务专用 skill，并在任务派发中写出触发语。
- 用户未指定 skill 时，不生成默认 skill routing。
- 同一生命周期和复用范围内只能有一个有效实例。
- 重复 workstream 出现时，A 主控必须暂停分派、选择主实例、合并输出并关闭重复实例。
- 最终收尾顺序是：环境核验 -> 实现证据 -> Review 通过 -> 审计通过 -> A 向用户汇报。
不会。它的职责是生成开发控制文档包。真正写代码发生在新的主控开发执行阶段。
可以。没有真实子智能体时，仍然要创建逻辑 workstream 记录，并按该 workstream 的权限、日志、证据和 Review 规则执行。
如果任务已经分派给 workstream，不能。除非用户显式授权、权限矩阵更新、进度文档记录职责变更，三者都满足。
不会。v0.6.1 默认不提交、不推送、不创建 PR。是否允许这些动作，必须在 plan 中选择，或由用户后续明确授权。
保持默认行为。v0.6.3 不会推断、不发明、不强制加入任何 skill。只有用户在输入中明确指定 skill 时，才会生成 global skill baseline 或 task/workstream skill routing。
因为不同项目的并行边界不同。这个 skill 要求先识别项目画像，再按实际模块、目录、服务、页面、命令、数据域或文档章节生成 workstream。
强化真实子智能体 reasoning effort 显式传递规则。
创建或派发真实子智能体时，A-main-control 必须优先读取权限矩阵中的 Recommended reasoning effort，并在任务说明或调用参数中显式传递或要求 reasoning_effort。只有目标 workstream 未配置推荐值时，才继承父会话默认 reasoning_effort 并记录 fallback。因成本、速度或工具限制调整推荐值时，必须先记录原因并获得 A-main-control 确认。
增加显式 skill routing 策略。
新版本支持用户在开始作 plan 前用自然语言指定两层 skill：一类是所有智能体继承的 global skill baseline，另一类是某类任务、某个 workstream、Review、审计或 one-shot assignment 专用的 task/workstream skill routing。
如果用户没有指定 skill，生成的 plan 和文档保持默认行为，不推断、不发明、不强制加入任何 skill。若用户指定了 skill，plan、启动提示词、总控入口、协作规范、任务进度记录和文档验收清单必须记录全局 skill、任务专用 skill、派发触发语和 required skill 不可用时的 fallback。
增加 reasoning effort 策略。
新版本要求生成 workstream registry、permission matrix 或任务分配时记录推荐思考程度：A-main-control 默认 high；最终裁决、跨 workstream 冲突、权限缺陷和最终审计使用 xhigh；普通 implementation workstream 默认 medium；简单查找、整理、格式化和低风险文档清理使用 low 或 medium；contract-review、security-review、progress-audit 和高风险 Review 使用 high，最终 closeout audit 使用 xhigh。
当真实 subagent 或调用接口支持 reasoning effort 时，A-main-control 必须在派发任务时设置或明确要求该档位；若平台不支持直接设置，也必须把推荐档位作为执行约束记录在文档中。v0.6.4 起，真实子智能体优先按权限矩阵 Recommended reasoning effort 显式传递或要求 reasoning_effort，只有矩阵未配置推荐值时才继承父会话默认值。
增加 Codex /goal 模式启动支持。
生成 00_新窗口启动提示词.md 时，除原有新窗口启动提示词外，还必须输出一段单独可复制的 /goal 执行目标，用于让新 Codex 窗口追踪主控开发长期目标。
新版同时明确默认不要提交代码、不要推送代码、不要创建 PR；只有项目 plan 或用户后续消息显式授权时，才允许把提交、PR 或推送作为收尾步骤。制作 plan 时需记录代码提交/推送策略，文档自检也必须确认启动提示词包含 /goal 目标块和默认不提交/推送规则。
对主 SKILL.md 做瘦身重构，移除补丁式重复表述，把长文档集清单和模板细节下沉到 references/ 与 assets/doc-templates/。
保留并强化四类硬规则：阶段边界、项目画像驱动 workstream、A 主控不得实现产品代码任务、子智能体复用与权限矩阵。
新版本把 skill 主体压缩为更短的规则型结构，同时保留自检和失败处理：若产品实现任务分配给 A 主控、重复创建 workstream、权限矩阵缺失或 A 已顺手执行 workstream 任务，均视为流程缺陷并要求回退修正。
修正“人类责任角色被误映射为 A 主控开发任务”的漏洞。
新版本明确区分 A 主控、Developer A/B 等人类责任角色和 implementation workstream：A 主控只能负责协调、Review 编排、进度审计和最终汇总；在多智能体主控开发执行阶段，产品代码、schema、OpenAPI、typed client、测试和部署脚本修改必须分配给权限矩阵中的 workstream 或逻辑 workstream。
若输入需求文档把任务写给 Developer A / Developer B，生成 agentic 文档时必须转换为具体 workstream 或 Review owner，不得把 Developer A 等同于 A 主控实现者。若输出文档把产品代码任务分配给 A 主控，必须视为文档缺陷并重写任务分配表。
加强子智能体复用和 A 主控执行边界。
新增“同一生命周期和复用范围内只能存在一个有效实例”的强制复用规则，要求 persistent / workstream / one-shot 分别按全局、任务流和一次性上下文管理；后续任务必须复用原实例或逻辑实例，重复创建时 A 主控必须暂停分派、合并输出并关闭重复实例。
新增 A 主控禁止顺手实现规则：已分派给 workstream 的开发任务不得由 A 主控以“改动小”“顺手”“方便”为理由直接完成；如需改为 A 直接执行，必须先获得用户显式授权、更新权限矩阵并在进度文档记录职责变更。
对于没有真实子智能体的平台，要求创建逻辑 workstream 记录，并按该 workstream 的权限、日志和验收证据执行，避免 A 主控身份和 worker 身份混写。
将多智能体角色设计从固定 B/C/D 模板升级为“项目画像驱动”的 workstream 生成机制。
新版本要求先识别项目类型、交付物、技术栈、可并行边界和共享风险，再生成对应的实现、契约、Review、审计或文档 workstream；同时强制输出权限矩阵，明确每个子智能体的可写范围、禁止范围、测试责任和 Review owner。
新增“启动前环境核验”模板，要求 A 主控在开发执行前先确认仓库、分支、脏改、子模块、依赖、测试命令、真实 subagent 能力和并行安全边界，降低新窗口协作开发时的误派发和越权修改风险。
优化了多智能体协作开发的阶段边界：保留文档生成阶段只读原则，同时明确新窗口进入“主控开发执行阶段”后，A 主控可以协调 worker 子智能体并行开发。
新增“新窗口启动提示词”模板，供用户复制到新 Codex 窗口后直接激活项目主控开发流程；同时补充 B/C/D 实现型 workstream 可写各自模块、E/R/Q 默认负责契约 Review 审计且通常只读的权限边界，并在总控入口、协作规范和文档验收清单中同步体现。
修复 SKILL.md 中文编码，升级为 v0.3.0。
新增子智能体生命周期策略、创建前决策门、agent_id 逻辑实例复用规则；优化协作规范模板，加入按项目裁剪的注册表、状态枚举、关闭记录；精简总控入口重复说明，并更新 openai.yaml 默认提示。
加入子智能体复用。
修改这个 skill 时，优先保持 SKILL.md 精简，把长模板、示例和文档集说明放到 assets/ 或 references/。
修改后至少检查：
SKILL.mdfrontmatter 是否仍然有效。- 版本号是否更新。
- 模板是否还能生成完整文档包。
00_新窗口启动提示词.template.md是否仍包含启动提示词和/goal目标。- reasoning effort 是否只使用
low、medium、high、xhigh。 - 未指定 skill 时是否保持默认空白；指定 skill 时是否记录两层 skill routing、触发语和 fallback。
- 权限矩阵、workstream 复用和 A 主控边界是否仍然明确。