awesome-copilot 实施计划生成模式用确定性模板打造 AI 可直接执行的 Implementation Plan【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot本篇技术指南以 implementation-plan.agent.md 为核心讲解 awesome-copilot 社区为 GitHub Copilot 定制的实施计划生成模式Implementation Plan Generation Mode——一种面向 AI-to-AI 通信的规划规范。读完本文你将掌握该 Agent 的执行上下文、Phase 架构、标识符前缀体系、/plan/目录下的计划文件命名约定以及可被自动校验的强制 Markdown 模板结构从而能亲手产出由 AI Agent 或人类零歧义执行、且能通过脚本级合规检查的实施计划。模式定位面向 AI-to-AI 执行的确定性规划在 awesome-copilot 的agents/目录中沉淀了大量供 GitHub Copilot 使用的定制 Agentcustom agentsimplementation-plan.agent.md 是其中专注于规划阶段的角色。它在 front matter 中声明了自身的模式名Implementation Plan Generation Mode描述为为新特性或既有代码重构生成实施计划Generate an implementation plan for new features or refactoring existing code并明确列出该模式可调用的工具集涵盖代码库搜索、用法追踪、问题读取、测试失败读取、终端输出、文件编辑、任务执行等。该模式的核心定位Primary Directive是You are an AI agent operating in planning mode. Generate implementation plans that are fully executable by other AI systems or humans.也就是说这个 Agent不写代码只输出结构化计划计划的下游消费者既可能是人也可能是另一个 AI。与之呼应的是执行上下文Execution Context条款——This mode is designed for AI-to-AI communication and automated processing. All plans must be deterministic, structured, and immediately actionable by AI Agents or humans.本模式为 AI 之间通信与自动化处理而设计所有计划必须确定、结构化且能被 AI Agent 或人立即执行。这一先计划、后编码、且计划本身可机器执行的理念在仓库中并非孤例。同为规划向的 plan.agent.md 以Think First, Code Later为第一原则强调实现前先理解代码库、澄清需求、形成策略而本文档则更进一步把规划结果本身格式化为一种可解析、可校验的工程产物。二者配合使用即可构成战略规划 → 实施计划落盘的完整链路。核心要求与不可逾越的红线该模式通过一节Core Requirements定义了计划产出的硬性标准共四条Generate implementation plans that are fully executable by AI agents or humans计划必须对 AI 与人同样可执行这是计划存在的唯一目的Use deterministic language with zero ambiguity语言必须确定零歧义不允许出现模棱两可的表述Structure all content for automated parsing and execution全部内容面向自动化解析与执行进行结构化组织Ensure complete self-containment with no external dependencies for understanding计划必须具备完整自包含性理解计划不需要依赖任何外部上下文DO NOT make any code edits - only generate structured plans处于该模式的 Agent 绝对不允许修改任何代码只生成结构化计划。最后一条尤其重要它与 task-planner 流派见 task-planner.agent.md中 interpret ALL user input as planning requests, NEVER as direct implementation requests 的规则互为印证规划型 Agent 与实施型 Agent 的职责边界是被明确分离的。Phase 架构原子化的阶段与任务拆分计划的组织单元不是自由文本而是离散、原子的阶段phases与可执行任务tasks。Phase Architecture 一节给出四条硬约束Each phase must have measurable completion criteria每个阶段必须有可度量的完成标准Tasks within phases must be executable in parallel unless dependencies are specified阶段内任务默认可并行除非显式声明依赖All task descriptions must include specific file paths, function names, and exact implementation details所有任务描述必须包含具体文件路径、函数名与精确的实现细节No task should require human interpretation or decision-making任何任务都不允许要求人工解读或决策。换句话说一个合格的实施计划应该能照单执行下游执行者无论 AI 还是人拿到的每个 TASK 都是自足的动作描述其依赖关系显式声明完成与否可被客观判定。这种默认并行 显式依赖的建模方式为多 Agent 或多机并行执行预留了空间。AI 优化实现标准与标识符前缀体系为了让计划天然利于机器解析文档提出了一组AI-Optimized Implementation Standards使用显式无歧义的语言要求零解读成本将所有内容组织为机器可解析格式表格、列表、结构化数据在适用处给出具体文件路径、行号与精确代码引用显式定义所有变量、常量与配置值在每个任务描述内提供完整上下文对所有标识符使用标准化前缀REQ-、TASK- 等包含可被自动验证的校验标准。其中标识符前缀体系是整个模板的骨架。仓库中与本文档配套的 create-implementation-plan/SKILL.md 进一步扩充了这一体系可用的声明前缀包括前缀含义典型声明位置REQ-NNN需求RequirementRequirements Constraints 小节SEC-NNN安全需求Requirements Constraints 小节CON-NNN约束ConstraintRequirements Constraints 小节GUD-NNN指导方针GuidelineRequirements Constraints 小节PAT-NNN应遵循的模式PatternRequirements Constraints 小节GOAL-NNN阶段目标各 Implementation Phase 标题下TASK-NNN可执行任务Phase 内任务表行ALT-NNN备选方案Alternatives 小节DEP-NNN依赖Dependencies 小节FILE-NNN受影响文件Files 小节TEST-NNN测试Testing 小节RISK-NNN风险Risks Assumptions 小节ASSUMPTION-NNN假设Risks Assumptions 小节需要注意的是create-implementation-plan/SKILL.md 中额外强调了一个关键语义每个标识符只能声明一次但可以被多次引用。声明指首次引入该标识符的位置任务表行的首格、或- **REQ-001**: ...这种加粗前缀的 bullet 行此后在任务正文、依赖小节等处再次出现该 ID 均属合法引用不算冲突。输出文件规范/plan/ 目录与命名约定模式要求将计划保存为独立文件并规定了明确的存放位置与命名规则计划文件统一存放在仓库/plan/目录文件命名遵循[purpose]-[component]-[version].mdpurpose 前缀限定为八类语义upgrade升级、refactor重构、feature特性、data数据、infrastructure基础设施、process流程、architecture架构、design设计文档给出的示例为upgrade-system-command-4.md、feature-auth-module-1.md文件必须是含合法 front matter 的标准 Markdown。这套命名规范的价值在于一眼可知用途仅凭文件名就能判断这份计划属于哪种变更类型、作用在哪个组件、处于哪个版本迭代便于在/plan/目录中长期积累与检索。强制模板结构八个必需小节逐一拆解文档规定所有实施计划必须严格遵循固定模板且每个小节都是必填项必须填入具体、可执行的内容AI Agent 在真正执行计划前必须先做模板合规校验validate template compliance before execution。下面按模板顺序逐一解析front matter 字段--- goal: [Concise Title Describing the Package Implementation Plans Goal] version: [Optional: e.g., 1.0, Date] date_created: [YYYY-MM-DD] last_updated: [Optional: YYYY-MM-DD] owner: [Optional: Team/Individual responsible for this spec] status: Completed|In progress|Planned|Deprecated|On Hold tags: [Optional: List of relevant tags or categories, e.g., feature, upgrade, chore, architecture, migration, bug etc] ---字段语义与取值约束如下goal一句话概括该计划要达到的目标必填version可选可填1.0这类语义化版本或日期date_created必填ISO 日期格式YYYY-MM-DDlast_updated可选YYYY-MM-DD用于追踪计划修订owner可选声明负责该规格的团队或个人status计划的当前生命周期状态只能取五个枚举值之一Completed已完成文档标注配亮绿色徽章In progress进行中黄色徽章Planned已规划蓝色徽章Deprecated已弃用红色徽章On Hold搁置橙色徽章。tags可选如feature、upgrade、chore、architecture、migration、bug等分类标签。注意status 不仅出现在 front matter还要求以徽章形式展示在 Introduction 部分使计划的当前状态在任何渲染场景下都一目了然。Introduction# Introduction  [A short concise introduction to the plan and the goal it is intended to achieve.]简要介绍计划本身及其试图达成的目标。由于仓库链接规范要求不引用外部资源实践中可将 status 徽章替换为内联文本标签如**Status: Planned**不影响语义。1. Requirements Constraints需求与约束显式列出所有影响计划并约束实现方式的需求与约束建议用 bullet 或表格呈现例如- **REQ-001**: Requirement 1 - **SEC-001**: Security Requirement 1 - **[3 LETTERS]-001**: Other Requirement 1 - **CON-001**: Constraint 1 - **GUD-001**: Guideline 1 - **PAT-001**: Pattern to follow 1其中SEC-专门用于安全类需求[3 LETTERS]-是一个可自由扩展三位字母代码的占位例如迁移类计划可自定义MIG-001保留了为领域定制标识符类型的空间。2. Implementation Steps实施步骤按Implementation Phase N组织每个阶段先声明一条阶段目标GOAL再用任务表列出该阶段的任务### Implementation Phase 1 - GOAL-001: [Describe the goal of this phase, e.g., Implement feature X, Refactor module Y, etc.] | Task | Description | Completed | Date | | -------- | --------------------- | --------- | ---------- | | TASK-001 | Description of task 1 | ✅ | 2025-04-25 | | TASK-002 | Description of task 2 | | | | TASK-003 | Description of task 3 | | |任务表固定为四列Task标识符、Description描述、Completed完成标记已完成用 ✅ 勾选未完成留空、Date完成日期。一个阶段对应一个或多个 GOAL一张表承载其全部 TASK。3. Alternatives备选方案以 bullet 列出曾考虑过但最终未采用的方案及其未选原因为所选方案提供背景与理由防止后人重复论证- **ALT-001**: Alternative approach 1 - **ALT-002**: Alternative approach 24. Dependencies依赖列出实现所依赖的库、框架或其他组件- **DEP-001**: Dependency 1 - **DEP-002**: Dependency 25. Files受影响文件列出将受该特性或重构影响的具体文件- **FILE-001**: Description of file 1 - **FILE-002**: Description of file 2结合 Phase 架构对必须包含具体文件路径的要求这里建议直接给出仓库内的相对路径使执行者无需额外推断。6. Testing测试列出为验证实现而需要编写的测试- **TEST-001**: Description of test 1 - **TEST-002**: Description of test 27. Risks Assumptions风险与假设列出与实现相关的风险及所做的假设- **RISK-001**: Risk 1 - **ASSUMPTION-001**: Assumption 1显式记录假设尤其重要——它是后续更新计划时最先被挑战的部分。8. Related Specifications / Further Reading相关规格 / 延伸阅读给出相关规格链接与外部资料链接帮助执行者在需要时获得更多背景。模板校验规则与脚本级合规检查为保证模板不被自由发挥破坏文档给出了四条 Template Validation RulesAll front matter fields must be present and properly formatted所有 front matter 字段必须存在且格式正确All section headers must match exactly (case-sensitive)所有小节标题必须逐字符精确匹配区分大小写All identifier prefixes must follow the specified format所有标识符前缀必须遵循规定格式Tables must include all required columns with specific task details表格必须包含全部必需列及具体任务细节No placeholder text may remain in the final output最终输出中不允许残留任何占位文本。在配套的 create-implementation-plan/SKILL.md 中这一校验被进一步工程化为一段可直接运行的 POSIX shell 脚本依赖grep、sed、sort、uniq用于在计划定稿前执行标识符唯一性检查# Set PLAN_FILE to the plan being validated. PLAN_FILE/plan/purpose-component-version.md # 1) Duplicate TASK / GOAL declarations in table rows. grep -oE \| (TASK|GOAL)-[0-9] \| $PLAN_FILE \ | sed -E s/.*((TASK|GOAL)-[0-9]).*/\1/ \ | sort | uniq -d # 2) Duplicate declaration IDs in bullet-style spec lines. grep -oE ^- \*\*(REQ|SEC|CON|GUD|RISK|ASSUMPTION|TASK|GOAL|FILE|TEST|PAT|ALT|DEP)-[0-9]\*\*: $PLAN_FILE \ | sed -E s/^- \*\*([A-Z]-[0-9])\*\*:.*/\1/ \ | sort | uniq -d # 3) Broad duplicate scan (diagnostic only; may include valid references). grep -oE (REQ|SEC|CON|GUD|RISK|ASSUMPTION|TASK|GOAL|FILE|TEST|PAT|ALT|DEP)-[0-9] $PLAN_FILE \ | sort | uniq -d三段检查的语义需要正确理解检查 (1) 针对任务表中的 TASK/GOAL 声明检查 (2) 针对 bullet 式声明行两者若返回任何重复行都必须重新编号直至为空这是门禁检查 (3) 是宽泛的信息性扫描会命中合法引用因此只作提示不做拦截。在缺少上述工具的 Windows 环境下应使用平台等效命令并保留同样的声明 vs 引用判定逻辑。计划的新建、更新与同仓库配套生态在 awesome-copilot 仓库中围绕这份实施计划模板形成了一个可观测的配套工具链体现为同类 Agent / Skill 的重复出现与互相引用新建与本文档内容几乎同源的 create-implementation-plan/SKILL.md 以${input:PlanPurpose}为输入负责为一个新特性/重构/升级/设计/架构/基础设施创建新的实施计划文件并在模板之上额外提供了上述标识符唯一性校验脚本与 Status 状态机可作为独立 skill 与本文档的 Agent 模式配合更新update-implementation-plan/SKILL.md 负责根据新增或更新的需求修订既有实施计划文件其输出要求与本文档完全同构——同样是确定性语言、原子化阶段、相同模板与校验规则从而保证新建与更新产出的计划风格一致、可互相衔接同族规划角色agents/下还有多个定位互补的规划 Agent如强调信息收集与架构权衡的 plan.agent.mdPlan Mode Strategic Planning Architecture、要求先验证研究资料再落盘三种规划文件plans/details/prompts并维护跨文件行号引用的 task-planner.agent.md、以及采用 TDD 阶段划分的红-绿-重构流程 Agenttdd-red.agent.md、tdd-green.agent.md、tdd-refactor.agent.md。实施计划生成模式生成的计划正可以作为这些下游实施型 Agent 的输入合同。在组织层面这种将计划产物提升为一等公民一等 Markdown 文件、可 grep 校验、可版本迭代的做法正是 awesome-copilot 所倡导的用文件配置让 Copilot 专业化specialize their Copilot coding agent through simple file-based configuration的体现——你可以直接参考 README.agents.md 了解如何将这类*.agent.md安装进 VS Code 并在 Chat 界面或 CCA 中激活。一个可照抄的完整计划骨架综合 front matter 与八个小节一个通过合规校验、可直接投入使用的计划骨架如下示例以一次feature类型的认证模块开发为例--- goal: Introduce a JWT-based authentication module with refresh-token rotation. version: 1.0 date_created: 2025-04-25 last_updated: 2025-04-25 owner: Platform Team status: Planned tags: [feature, security, architecture] --- # Introduction **Status: Planned** 本计划为仓库新增认证模块使 API 具备签发与轮换 JWT 的能力并保证新增逻辑不破坏既有会话行为。 ## 1. Requirements Constraints - **REQ-001**: 签发 access token 与 refresh token二者均须携带用户 ID 声明。 - **SEC-001**: refresh token 必须支持服务端吊销禁止明文落库。 - **CON-001**: 不得引入新的全局单例依赖通过现有依赖注入容器提供。 - **GUD-001**: 错误消息不得泄露 token 细节。 - **PAT-001**: 遵循仓库现有的 repository 模式访问用户数据。 ## 2. Implementation Steps ### Implementation Phase 1 - GOAL-001: 实现 token 签发与刷新所需的底层服务。 | Task | Description | Completed | Date | | -------- | ---------------------------------------------------- | --------- | ---------- | | TASK-001 | 在 src/auth/ 下新建 JwtService封装签发与验签逻辑 | | | | TASK-002 | 为 refresh token 增加 DB 表并实现 repository 方法 | | | ### Implementation Phase 2 - GOAL-002: 暴露认证端点并接入现有路由。 | Task | Description | Completed | Date | | -------- | ---------------------------------------------------- | --------- | ---- | | TASK-003 | 在 controllers 中注册 login/refresh 路由 | | | | TASK-004 | 将中间件接入全局鉴权管线 | | | ## 3. Alternatives - **ALT-001**: 自建 session 存储——被否决因需额外维护会话状态且不利于水平扩展。 - **ALT-002**: 引入第三方 OAuth 网关——被否决因当前阶段成本过高。 ## 4. Dependencies - **DEP-001**: joseJWT 编解码版本按 package.json 锁定。 - **DEP-002**: 现有用户 Repository 接口。 ## 5. Files - **FILE-001**: src/auth/JwtService.ts新建 - **FILE-002**: src/auth/token.repository.ts新建 - **FILE-003**: src/routes/auth.routes.ts修改 ## 6. Testing - **TEST-001**: JwtService 单元测试过期、篡改、签名错误用例。 - **TEST-002**: login/refresh 端点集成测试含吊销后刷新被拒。 ## 7. Risks Assumptions - **RISK-001**: JWT 密钥轮换期间可能短暂影响已登录会话。 - **ASSUMPTION-001**: 现有用户表主键稳定可作为 token 声明来源。 ## 8. Related Specifications / Further Reading - 安全加固细则参考同仓库 security 相关 instructions。 - 相关既有规范specification agent 生成的接口规格文档。小结实施计划生成模式agents/implementation-plan.agent.md解决的是 AI 时代规划文档如何可执行这一根本问题通过确定性语言、原子化 Phase、编号标识符、固定目录与命名、机器可校验的强制模板把传统上仅供人阅读的计划改造成 AI Agent 与人共享的执行合同。配合仓库中同源的 create/update skill 与规划型 Agent 家族它构成了一个自洽的计划驱动开发闭环——先有可校验的计划再有按计划执行的实现。对希望让 Copilot 承担复杂多步变更的团队而言这是可以直接借鉴并落地的工程范式。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
