philip-cao-9527/code-note-helper/agents-md-creator

agents-md-creator

技能定位

生成项目级 AGENTS.md。这个 skill 只负责把长期协作规则整理成项目可执行约束，不负责实现业务功能，也不把某个旧项目的规则原样套到新项目。

AGENTS.md 应该回答：这个项目里 Agent 开始工作前必须知道什么、什么不能做、怎么验证、怎么汇报、什么时候升版或写报告。它不是一次性任务 prompt，也不是某个项目私有规则的复制品。

使用流程

1. 先确认目标项目路径、项目类型、主要操作系统、默认 shell、用户希望长期生效的规则范围。
2. 读取目标项目的最小真实上下文：

• 已存在的 AGENTS.md、AGENTS.override.md、.codex/AGENTS.md 或同类项目规则文件。
• README.md、开发日志、贡献指南、测试说明、发布说明、变更记录。
• 与项目形态直接相关的入口文件、配置文件、脚本清单和包管理文件。
• 用户提供的参考项目规则或 skill，只学习组织方式和边界表达，不复制私有路径、模块名、版本号或测试命令。

1. 读取 references/agents-template.md，按目标项目事实裁剪：

• 保留通用底线：语言、编码、证据、测试、版本、报告、错误处理、输出格式。
• 用 {{...}} 占位符或目标项目真实值替换模板变量。
• 按 {{项目类型}} 和 {{风险域}} 启用项目专项段落，不适用就删除。专项段落可以参考 UI、数据、服务、模型、构建、部署、文档模板等场景，但不能写成所有项目默认规则。

1. 明确区分三类内容：

• 长期底线：不把未验证写成已验证、不吞异常、不做无关重构、先读真实调用链。
• 项目事实：真实目录、真实命令、真实版本策略、真实发布方式。
• 可选偏好：只有用户确认或项目证据支持时才写入。

1. 如果旧规则与目标项目事实冲突，以目标项目当前文件和用户最新决策为准。
2. 生成或改写 AGENTS.md 后，运行专项校验脚本：

python -X utf8 vibe-coding-template/skills/agents-md-creator/scripts/validate_agents_md.py path/to/AGENTS.md

脚本失败时，必须继续补齐目标 AGENTS.md 或模板，并复跑直到通过。该脚本只检查项目级规则的关键结构和质量约束，不判断具体项目规则是否已经完全贴合业务事实。

报告链接规则必须保留以下原文，不能改写、压缩或同义替换；validate_agents_md.py 会按完整字符串强制校验：

生成报告时必须使用可跳转的 Markdown 相对路径交叉引用。链接优先落到具体文件名，能定位到行号时必须使用 [文件名](相对路径#L行号) 范式；不要把 :行号 写进链接目标里。不要只写文件夹名代替关键证据，也不要使用当前 IDE 无法跳转的绝对路径，必须强制使用相对路径。

输出要求

• 输出一份完整、可落地的 AGENTS.md 内容或补丁方案。
• 规则要能直接指导后续 Agent 工作，避免空泛口号。
• 必须包含执行环境前置规则、顶层代码生成约束、修改前必读、测试验证、版本规则、修复报告规则、输出与验收格式、进度播报格式、错误处理和无依据保护逻辑判断框架。
• 不要把某一类项目的发布审核、权限、评测、数据迁移、真实服务复测等专项约束无条件写成所有项目通用规则。
• 如果有未确认事实，写成待确认项或 {{占位符}}，不要包装成项目规则。
• 不得删除执行环境前置规则、顶层代码生成约束、版本规则、fix-report 规则、无依据保护逻辑、错误处理、输出与验收格式和进度播报格式；如确实裁剪，必须逐条说明原因和替代约束。

质量标准

• 最终 AGENTS.md 要像项目规则，不像教程、建议或说明文档。
• 每条关键约束都应可检查、可执行、可交付。
• “最小必要改动”必须允许在有真实依据时进行较大重构，不能变成盲目保守。
• 版本和报告规则必须模板化，不得写死某个项目的版本文件、报告目录或发布渠道。
• 输出格式和进度播报格式必须清楚，方便长任务取证和最终验收。

自检

输出前逐条检查：

1. 是否先读了目标项目真实上下文。
2. 是否删除了不适用于目标项目的旧项目规则。
3. 是否把长期通用行为放进 AGENTS.md，而不是塞进一次性 prompt 模板。
4. 是否没有写死旧项目私有路径、模块名、测试命令、版本号或审核规则。
5. 是否补齐版本规则、fix-report 规则、输出验收格式和进度播报格式。
6. 是否明确禁止为了“看起来更稳”新增没有依据的保护逻辑，并要求说明依据、影响、可观测性、验证方式和后续调整方式。
7. 是否没有保留空标题、英文占位说明、机器味模板句或不可复用硬编码。
8. 是否已运行 validate_agents_md.py，并根据失败项循环修改到通过。