Copilot Team Scaffold#

为新项目搭建完整的 AI 辅助开发框架。把 Copilot 从代码补全工具变成一个有组织、有纪律的虚拟开发团队。

核心理念#

text

需求文档 → 设计规格 → 任务分解 → Agent 分发执行 → 自动化保障（hooks + instructions）

通过以下四层保障 AI 执行质量：

• 文件化的约束（AGENTS.md）— 明确每个角色的职责和规范
• 自动化的保障（hooks）— 覆盖 6 个生命周期事件：上下文注入、质量门禁、降级策略
• 持久化的记忆（memories + sessions + lessons）— 弥补 AI 的上下文遗忘，自动积累教训
• 结构化的任务（spec-flow + tasks.md）— 确保需求到代码的可追溯性

运行时生命周期#

text

SessionStart ──→ PreToolUse ──→ PostToolUse ──→ SubagentStart ──→ SubagentStop ──→ Stop
     │                │               │               │                │            │
  计划恢复         计划上下文       更新提醒       审计记录       质量验证门禁     完成度检查
  教训注入         AGENTS门控      编辑追踪                       降级策略        AGENTS同步检查
  趋势分析         新模块阻断      新目录提醒                                     会话摘要
  门控/追踪初始化

AGENTS.md 全生命周期保障#

text

SessionStart → 初始化门控(.agents-gate) + 编辑追踪(.code-edits)
      │
PreToolUse  → 写代码前必须先读过 AGENTS.md（门控）
      │        create_file 到无 AGENTS.md 的模块目录 → 阻断
      │
PostToolUse → 记录 read_file AGENTS.md → 打开门控
      │        追踪代码 + AGENTS.md 编辑到 .code-edits
      │        create_file 到无 AGENTS.md 的目录 → 软提醒
      │
Stop        → 比对 .code-edits：代码改了但 AGENTS.md 没改 → 阻断

学习闭环#

text

失败 → 自动记录(lessons-learned.md) → 统计分析(趋势) → 注入新会话 → 预防重犯

前提条件#

此 skill 假设以下全局 skill 已安装：

• spec-flow — 需求拆解工作流（proposal → requirements → design → tasks）
• planning-with-files — 会话级文件计划（可选，将作为项目级 skill 生成）

⚠️ 交互规则#

使用 分阶段确认 工作流。每个阶段完成后等待用户确认再继续。

---

Phase 1: 采集项目信息#

向用户提出以下问题（使用 vscode_askQuestions 或对话形式）：

必填信息#

1. 项目名称：用于 spec-flow 目录名和 AGENTS.md 标题（如 CMC-ARD系统）

2. 项目简述：一句话描述项目做什么

3. 后端技术栈（选择一项）：

   • Python / FastAPI + Tortoise ORM
   • Python / FastAPI + SQLAlchemy
   • Python / Django
   • Node.js / Express
   • Go / Gin
   • Java / Spring Boot
   • 无后端

4. 前端技术栈（选择一项）：

   • React + TypeScript + Ant Design
   • React + TypeScript + MUI
   • Vue 3 + TypeScript
   • Next.js
   • 无前端

5. 数据库（选择一项）：

   • Azure SQL Server
   • PostgreSQL
   • MySQL
   • SQLite
   • MongoDB
   • 无数据库

6. 需要哪些 Agent 角色（多选，建议全选相关的）：

   • 后端开发Agent
   • 前端开发Agent
   • AI工程师Agent
   • 测试工程师Agent
   • 需求分析工程师Agent
   • 架构师Agent（只读不写代码）

可选信息#

1. 认证方式：SSO JWT / 自建用户系统 / 无认证
2. CI/CD：Docker Compose / GitHub Actions / Azure DevOps / 无
3. 表前缀：数据库表名前缀（如 custom_ardqc_）
4. 代码检查工具：ruff（Python）/ eslint（TS）/ 其他

Phase 1 完成后#

输出采集到的配置摘要，等待用户确认：

text

📋 **项目信息采集完成**

- 项目名：{{PROJECT_NAME}}
- 后端：{{BACKEND_STACK}}
- 前端：{{FRONTEND_STACK}}
- 数据库：{{DATABASE}}
- Agent 角色：{{AGENT_LIST}}

✅ 确认无误后说 "继续" 开始生成文件
✏️ 有修改请直接说

---

Phase 2: 生成静态文件#

以下文件 直接从 templates/ 目录复制，无需定制：

2.1 Hooks（自动化钩子）#

从 templates/hooks/ 复制到项目的 .github/hooks/：

text

.github/hooks/
├── planning-with-files.json          # 全生命周期 hook 配置（6 个事件）
├── post-tool-lint.json               # 自动 lint hook 配置
├── post-tool-lint.js                 # lint 执行脚本
└── scripts/
    ├── planning-paths.js             # 路径解析共享模块
    ├── session-log.js                # 审计日志共享模块
    ├── session-start.js              # SessionStart: 恢复上下文 + 教训注入 + 趋势分析 + 门控初始化
    ├── pre-tool-use.js               # PreToolUse: AGENTS.md 门控 + 新模块阻断 + 计划注入
    ├── post-tool-use.js              # PostToolUse: AGENTS.md 追踪 + 编辑记录 + 新目录提醒
    ├── subagent-start.js             # SubagentStart: 审计记录
    ├── subagent-stop.js              # SubagentStop: 质量验证门禁 + 降级策略
    └── agent-stop.js                 # Stop: AGENTS.md 同步检查 + 完成度检查 + 会话摘要

planning-with-files.json 覆盖 6 个生命周期事件：

• SessionStart(15s) — 计划恢复 + 教训注入 + 趋势分析 + 日志清理 + AGENTS.md 门控/编辑追踪初始化
• PreToolUse(15s) — AGENTS.md 门控（写代码前须先读 AGENTS.md）+ 新模块目录 AGENTS.md 强制创建 + 计划上下文注入
• PostToolUse(15s) — AGENTS.md 门控追踪 + 代码编辑追踪 + 新目录 AGENTS.md 提醒 + 计划更新提醒
• SubagentStart(10s) — 审计记录 Agent 启动
• SubagentStop(120s) — 核心门禁：ruff + pyright + tsc + 关联测试 + 降级策略
• Stop(10s) — AGENTS.md 同步检查（代码改了但 AGENTS.md 没更新 → 阻断）+ 任务完成度检查 + 会话摘要

SubagentStop 验证门禁 详解：

1. git diff 获取变更文件列表
2. Python 文件 → ruff check + pyright
3. TypeScript 文件 → tsc --noEmit
4. 自动映射关联测试文件并运行（pytest / vitest）
5. 验证失败 → block 让 agent 继续修复
6. 连续失败 3 次 → 降级到人工，不再 block（防止死循环）
7. 每次失败自动追加到 lessons-learned.md

session-log.js 共享模块：

• appendLog(sessionId, event, details) — 结构化日志追加
• cleanupLogs() — 自动清理过期日志（>30天 / >100个）+ 过期重试计数器（>1天）
• 日志文件格式： .github/session-logs/YYYY-MM-DD_<sid8>.md

2.2 planning-with-files Skill（项目级）#

从 templates/skills/planning-with-files/ 复制到 .github/skills/planning-with-files/：

text

.github/skills/planning-with-files/
├── SKILL.md                          # Skill 定义
├── templates/
│   ├── task_plan.md
│   ├── findings.md
│   └── progress.md
└── scripts/
    └── session-catchup.py

2.3 Sessions 工作区#

从 templates/docs/ 复制：

text

docs/sessions/README.md               # 会话目录说明

---

Phase 3: 生成动态文件#

以下文件需要根据 Phase 1 采集的信息 动态生成。

3.1 根 AGENTS.md#

创建 AGENTS.md，结构如下（用采集到的信息填充）：

markdown

# {{PROJECT_NAME}} — Project Guidelines

> 根目录 AGENTS.md — 全局规则，适用于所有模块。
> 子模块细节见各目录下的 `AGENTS.md`。

## 项目概述
{{PROJECT_DESCRIPTION}}

## 架构
{{根据技术栈生成架构图}}

## 安全合规
- 禁止硬编码敏感信息
- 日志脱敏
- 输入验证
- .env 不入库

## 配置管理
{{根据技术栈生成配置说明}}

## 代码质量
- 类型安全
- 异步编程
- 错误处理
- 结构化日志
- 代码简洁性

## 数据库
{{如有数据库，生成表前缀和数据隔离规则}}

## 测试策略
| 模式 | 适用场景 |
|------|----------|
| TDD | 纯逻辑、边界条件多 |
| 边写边测 | REST 端点 |
| 实现后补 | AI 输出/UI 交互 |

## Agent 分配规则
{{根据选择的 Agent 角色生成分配表}}

## Agent 执行约定
1. 执行前：读取目标模块的 AGENTS.md
2. 执行中：遵守安全合规与代码质量要求
3. 联合开发：读取相关模块 AGENTS.md，确保接口兼容
4. 自动分发：根据任务类型通过 runSubagent 分发给对应 Agent
5. 跨模块感知：识别所有受影响模块，分别调度对应 Agent

## 模块 AGENTS.md 规则
- 每个模块开发前须先创建该模块的 AGENTS.md
- 必须包含：模块功能、技术栈、接口定义、数据模型、注意事项
- 功能变更后同步更新

## 构建与运行
{{根据技术栈生成命令}}

3.2 Agent 定义文件#

为每个选择的 Agent 在 .github/agents/ 下创建 .agent.md。

Agent 文件基本结构（以后端开发Agent为例）：

markdown

---
description: "后端开发Agent。Use when implementing backend API endpoints, routes, ORM models, schemas, business services, or any backend code. Triggers: 后端开发, backend, API开发, 服务端, {{BACKEND_FRAMEWORK}}, ORM, schema, service, 数据库"
name: "后端开发Agent"
tools: [read, edit, search, execute, agent, todo]
---

你是 {{PROJECT_NAME}} 的**后端开发专家**。

## 角色定位
你负责所有后端代码的开发，包括 API 端点、ORM 模型、Schema、业务服务层、后台任务。

## 技术栈
{{根据后端技术栈填充}}

## 执行前准备
1. 阅读 `.spec-flow/active/{{PROJECT_SLUG}}/design.md` 中的相关章节
2. 阅读目标模块的 `AGENTS.md` 文件
3. 检查依赖任务是否已完成
4. 创建新模块时，必须先创建该模块的 `AGENTS.md`

## 约束
- 遵守根目录 AGENTS.md 的安全合规和代码质量要求
- 所有 API 必须 async/await
- 使用结构化日志
- 类型安全

各角色要点：

Agent文件名关键特征后端开发Agentbackend-developer.agent.md负责 API/ORM/Service/Task前端开发Agentfrontend-developer.agent.md负责组件/Hooks/状态管理/i18nAI工程师Agentai-engineer.agent.md负责 LLM/文档解析/规则引擎测试工程师Agenttest-engineer.agent.md负责 pytest/vitest/覆盖率需求分析工程师Agentrequirements-analyst.agent.md负责文档/手册/需求追踪架构师Agentarchitect.agent.md只读不写代码，负责设计评审

3.3 Instructions（指令约束）#

在 .github/instructions/ 下生成：

3.3.1 通用 Instructions（直接复制）

• planning-with-files.instructions.md — 从 templates/instructions/ 复制
• testing.instructions.md — 从 templates/instructions/ 复制
• spec-flow-run-task.instructions.md — 从 templates/instructions/ 复制（需替换 {{PROJECT_SLUG}}）

3.3.2 技术栈 Instructions（动态生成）

如果有后端，生成 backend-*.instructions.md，包含：

• 该后端框架的异步模式约束
• ORM 使用规范
• 日志框架约束
• lint 工具和配置

如果有前端，生成 frontend-*.instructions.md，包含：

• 组件规范
• i18n 规则
• 状态管理约束
• UI 框架使用规范

3.4 run-task.prompt.md#

在 .github/prompts/ 下生成：

markdown

---
description: "Execute a task from tasks.md by task ID (e.g. T-008)."
agent: "agent"
argument-hint: "Task ID, e.g. T-008"
---
Execute the following task from the project task list.

## Steps

1. Read the task list: [tasks.md](.spec-flow/active/{{PROJECT_SLUG}}/tasks.md)
2. Find the task matching `{{ input }}` — extract its description, dependencies, status, complexity, and assigned Agent
3. **Dependency check**: If any dependency task is not ✅ Done, stop and report which are blocking
4. **Read module AGENTS.md**: Read the `AGENTS.md` file(s) for the target module(s)
5. **Execute**: Implement the task following the constraints in [AGENTS.md](AGENTS.md)
6. **Test**: If the task's test mode is TDD or 边写边测, write/update tests
7. **Verify**: Run the relevant test suite and confirm passing
8. **Report**: Summarize what was done, files changed, and any follow-up needed

---

Phase 4: 初始化 Spec-Flow 落地目录#

创建 spec-flow 的项目落地目录：

text

.spec-flow/active/{{PROJECT_SLUG}}/

不要 在这里创建 proposal.md / requirements.md 等文件 — 那些由 spec-flow skill 在实际执行时生成。只创建空目录。

---

Phase 5: 初始化数据层与记忆模板#

5.1 教训知识库#

从 templates/lessons-learned.md 复制到 .github/lessons-learned.md。此文件由 SubagentStop hook 自动写入验证失败记录，SessionStart hook 自动读取注入。

5.2 审计日志目录#

创建 .github/session-logs/ 目录（空），并在项目 .gitignore 中添加：

text

# Copilot session logs (auto-generated, not tracked)
.github/session-logs/

5.3 记忆模板#

提示用户手动或通过 memory tool 创建以下仓库级记忆文件：

text

/memories/repo/code-style.md      — 代码风格备忘（空模板，使用中积累）
/memories/repo/execution-discipline.md — 执行纪律备忘（空模板，犯错后记录）

内容建议：

code-style.md:

markdown

# 代码风格备忘

<!-- 使用过程中积累的代码风格约定 -->

execution-discipline.md:

markdown

# 执行纪律备忘

## 任务执行 Checklist（每个任务必须）

1. 完整读取 tasks.md §0 — 开发约束、Agent规则、执行约定
2. 必须通过 runSubagent 派发给指定 Agent 执行
3. 模块开发前先创建该模块的 AGENTS.md
4. 执行前准备 — 读 AGENTS.md → 了解模块结构 → 检查依赖完成
5. 安全合规 — 禁止硬编码密码、日志脱敏、输入验证
6. 代码质量 — 类型提示、async/await、错误处理、结构化日志
7. 测试策略 — 按任务指定的测试模式执行

## 教训

<!-- 犯错后在此记录，避免重复 -->

5.4 全局用户记忆（首次使用框架时初始化）#

通过 memory tool 检查并创建 以下全局记忆文件。这些文件跨项目持久化，每次会话自动加载到上下文中。 如果已存在则跳过（ memory create 对已有文件会失败，这是预期行为）。

/memories/agent-principles.md — Agent 行为原则

markdown

# Agent 行为原则（跨项目通用）

## 独立技术判断
- 用户提问 ≠ 要求修改；先独立分析对错，再给结论
- 推理基于技术事实，不基于"用户暗示了方向"

## 先讨论后动手
- 收到功能修改/新增请求时，**不要直接改代码**，先给出修改方案与用户讨论
- 用户明确确认方案后才可开始写代码

## 约束优先
- 执行任务前先读项目约束文件（AGENTS.md、instructions/），不因任务简单就跳过
- 安全合规不可跳过：禁止硬编码敏感信息、日志脱敏、输入验证

## 待办状态即时更新（严格执行）
- 每完成一个 todo，**立即调用 manage_todo_list 标记 completed**，再做下一个
- 禁止批量完成后一次性更新——上下文压缩会吞掉未持久化的状态
- 节奏：mark in-progress → 执行 → mark completed → 下一个 mark in-progress

## 分析→分发→执行
- 多模块任务先全面分析，再按职责分派给对应 Agent（runSubagent），不由主 Agent 直接写任务代码
- 模块开发前先读取/创建该模块的 AGENTS.md；功能变更后同步更新
- ⚠️ **AGENTS.md 同步是硬约束**：每次修改代码后，必须在同一轮操作中更新涉及模块的 AGENTS.md，不得遗留到用户提醒后再补

/memories/copilot-hooks.md — Hooks 配置笔记

markdown

# Copilot Chat Hooks 配置笔记

- 文档：https://code.visualstudio.com/docs/copilot/customization/hooks
- 配置位置：`.github/hooks/*.json`（项目级）、`~/.copilot/hooks/`（全局级）
- 事件名必须 PascalCase：SessionStart, PreToolUse, PostToolUse, Stop, SubagentStart, SubagentStop
- 需同时设 `command`（默认）+ `windows`（Windows 覆盖）；`bash` 仅映射 osx/linux

## Windows 环境
- bash.exe 在 RemoteApp 下会弹控制台窗口 → 已全部迁移到 Node.js 脚本
- hook 脚本用 `.js` + `node` 执行，子进程加 `windowsHide: true`

执行逻辑：对每个文件先用 memory view 检查是否存在，不存在才用 memory create 创建。已有文件保持不动，不覆盖用户积累的个性化内容。

---

Phase 6: 输出检查清单#

全部文件生成后，输出最终清单：

text

✅ **AI 开发框架初始化完成**

### 已创建文件

**Hooks（自动化保障 — 6 个生命周期事件）:**
- .github/hooks/planning-with-files.json（6 事件配置）
- .github/hooks/post-tool-lint.json + post-tool-lint.js
- .github/hooks/scripts/ (8 个脚本：planning-paths, session-log, session-start, pre-tool-use, post-tool-use, subagent-start, subagent-stop, agent-stop)

**Skills（技能包）:**
- .github/skills/planning-with-files/ (SKILL.md + templates + scripts)

**Agents（专职角色）:**
- .github/agents/ ({{N}} 个 Agent 定义文件)

**Instructions（约束注入）:**
- .github/instructions/ ({{N}} 个指令文件)

**Prompts（快捷入口）:**
- .github/prompts/run-task.prompt.md

**数据层（学习闭环）:**
- .github/lessons-learned.md（教训知识库，SubagentStop 自动写入）
- .github/session-logs/（审计日志目录，已加入 .gitignore）

**记忆文件（3 层记忆体系）:**
- /memories/agent-principles.md（全局 — Agent 行为原则，首次创建）
- /memories/copilot-hooks.md（全局 — Hooks 配置笔记，首次创建）
- /memories/repo/code-style.md（仓库级 — 代码风格备忘）
- /memories/repo/execution-discipline.md（仓库级 — 执行纪律备忘）

**项目文档:**
- AGENTS.md（根级约束）
- docs/sessions/README.md

**Spec-Flow 落地目录:**
- .spec-flow/active/{{PROJECT_SLUG}}/

### 运行时保障一览

| 事件 | 脚本 | 功能 |
|------|------|------|
| SessionStart | session-start.js | 计划恢复 + 趋势分析 + 教训注入 + 日志清理 + 门控初始化 |
| PreToolUse | pre-tool-use.js | AGENTS.md 门控 + 新模块阻断 + 计划注入 |
| PostToolUse | post-tool-use.js | AGENTS.md 追踪 + 编辑记录 + 新目录提醒 + 计划更新提醒 |
| SubagentStart | subagent-start.js | 审计记录 Agent 启动 |
| SubagentStop | subagent-stop.js | 质量门禁 + 降级策略 + 教训记录 |
| Stop | agent-stop.js | AGENTS.md 同步检查 + 完成度检查 + 会话摘要 |

### 下一步

1. 🔧 根据项目实际需求完善 `AGENTS.md` 中的架构图和配置说明
2. 📝 说 **"spec-flow"** 或 **"spec mode"** 开始拆解需求
3. 🚀 需求拆解完成后，说 **/run-task T-001** 开始执行第一个任务
4. 📊 SubagentStop 会自动验证代码质量，lessons-learned.md 自动积累经验

---

静态文件内容参考#

以下文件内容存放在 templates/ 目录中，scaffold 执行时直接复制到目标项目。详见各模板文件。

post-tool-lint.js 适配说明#

模板中的 lint 脚本支持 Python（ruff）和 TypeScript（eslint）。如果项目使用其他语言/lint 工具，在 Phase 2 复制后需要修改 post-tool-lint.js 中的扩展名判断和工具调用。

planning-paths.js 配置#

默认 PLANNING_ROOT = 'docs/sessions'。如果项目需要不同的会话目录，可通过环境变量 PLANNING_WITH_FILES_ROOT 覆盖。

spec-flow-run-task.instructions.md 路径#

模板中使用 {{PROJECT_SLUG}} 占位符，需替换为实际的 spec-flow 目录名。例如 .spec-flow/active/CMC-ARD系统/tasks.md。