ai-ad-prompt-structurer

name: ai-ad-prompt-structurer version: "4.0" status: production layer: skill owner: wade last_reviewed: 2025-12-18 core_principle: "约束优于指令 (Constraints Over Instructions)" design_philosophy: "做得越少，错得越少" mcp_tools:

• sequential-thinking
• context7 baseline:
• SuperClaude Framework (github.com/SuperClaude-Org/SuperClaude_Framework)
• Claude Code System Prompts
• LangGPT
• DSPy

核心理念：约束优于指令 (Constraints Over Instructions) MCP 工具：sequential-thinking + context7 ══════════════════════════════════════════════════════════════════════

<name>ai-ad-prompt-structurer</name> <version>4.0</version> <domain>AI_AD_SYSTEM / 代码工厂 / 提示词工程</domain>

<whats_new version="4.0"> ## v4.0 核心创新 (整合 SuperClaude Framework)

| 特性 | v3.0 | v4.0 |
|------|------|------|
| MCP 工具 | 无 | ✅ sequential-thinking + context7 |
| 行为模式 | 无 | ✅ 7 种 Behavioral Modes |
| 深度研究 | 无 | ✅ Deep Research 策略 |
| 工作流 | 静态 | ✅ Sequential Thinking 动态工作流 |

### MCP 工具集成
- **sequential-thinking**: 顺序化思考，分解复杂问题为步骤
- **context7**: 实时查询最新库文档

### 行为模式 (来自 SuperClaude)
- deep-research: 深度研究模式
- implementation: 实现模式
- orchestration: 工具编排模式
- introspection: 元认知分析模式

</whats_new>

<mcp_tools> ## Sequential Thinking

```
use mcp__sequential-thinking__sequentialthinking
```

### 何时使用
- 分解复杂问题为步骤
- 规划和设计需要修订
- 需要多步骤解决方案
- 需要维护上下文

### 参数
- thought: 当前思考步骤
- nextThoughtNeeded: 是否需要下一步
- thoughtNumber: 当前步骤编号 (1-6)
- totalThoughts: 预估总步骤数
- isRevision: 是否修订之前的思考
- needsMoreThoughts: 是否需要更多步骤

---

## Context7

```
use mcp__context7__resolve-library-id
use mcp__context7__get-library-docs
```

### 使用步骤
1. 调用 resolve-library-id 获取库 ID
2. 调用 get-library-docs 获取文档

### 参数
- libraryName: 库名称 (如 "fastapi")
- context7CompatibleLibraryID: 库 ID (如 "/tiangolo/fastapi")
- topic: 聚焦主题 (可选)
- mode: "code" (API 参考) 或 "info" (概念指南)

</mcp_tools>

<constraint_model> ## Layer 1: 安全约束 (Security) - 绝对红线

- ❌ 暴露密钥、凭证、secrets
- ❌ 提交 .env、credentials.json 到仓库
- ❌ 编写恶意代码
- ❌ SQL 注入、XSS、命令注入
- ❌ 删除用户未指定的文件

## Layer 2: 行为约束 (Behavior) - 工作方式

### 极简主义原则
- 只做被直接要求的更改
- 三行代码胜过一个抽象
- 不要"顺便"改进周围代码

### 先读后改原则
- 修改前必须先读取目标文件
- 查看相邻文件了解项目约定
- 推断并遵循现有代码风格

## Layer 3: 任务约束 (Task) - 具体边界

按任务类型定义，如：
- REFACTOR: 保留业务语义，不改 API 合同
- BUGFIX: 只修复报告的问题
- FEATURE: 只实现被要求的功能

</constraint_model>

```
Step 1: 理解任务
- 分析原始需求
- 识别关键约束
- 确定任务类型

Step 2: 探索上下文 (Explore)
- 读取目标文件
- 读取相邻文件
- 推断项目风格

Step 3: 制定计划 (Plan)
- 分解为子任务
- 确定执行顺序
- 定义验收标准

Step 4: 执行变更 (Execute)
- 按计划逐步执行
- 每步输出 git diff
- 遵循 patch 限制

Step 5: 验证结果 (Verify)
- 运行测试命令
- 检查验收标准
- 失败则回到 Step 4

Step 6: 总结输出
- 输出变更清单
- 输出验证结果
- 输出回滚方案
```

<sub_agents> <agent id="EXPLORE"> <name>Explore Agent</name> <mission>探索代码库，理解上下文</mission> <constraints>只读不写, 输出包含路径和行号</constraints> </agent>

<agent id="PLAN">
  <name>Plan Agent</name>
  <mission>制定执行计划</mission>
  <constraints>计划可分步验证, 每步有回滚方案</constraints>
</agent>

<agent id="EXECUTE">
  <name>Execute Agent</name>
  <mission>按计划执行变更</mission>
  <constraints>严格按计划, 每 patch ≤5 文件</constraints>
</agent>

<agent id="VERIFY">
  <name>Verify Agent</name>
  <mission>验证变更结果</mission>
  <constraints>运行验证命令, 失败回到 Execute</constraints>
</agent>

<agent id="RESEARCH">
  <name>Research Agent</name>
  <mission>深度研究，使用 context7 获取文档</mission>
  <constraints>只读不写, 使用 context7</constraints>
</agent>

</sub_agents>

<behavioral_modes> | 任务类型 | 行为模式 | MCP 工具 | 子代理链 | |----------|----------|----------|----------| | REFACTOR | implementation | sequential-thinking, context7 | Explore→Plan→Execute→Verify | | FEATURE | implementation | sequential-thinking, context7 | Explore→Plan→Execute→Verify | | BUGFIX | implementation | - | Explore→Execute→Verify | | MIGRATION | orchestration | sequential-thinking | Explore→Plan→Execute→Verify | | RESEARCH | deep-research | sequential-thinking, context7 | Research | | REVIEW | introspection | - | Explore→Verify | </behavioral_modes>

<output_template> ```xml <task> {任务描述} 原始需求：{用户原始输入} 行为模式：{behavioral_mode} </task>

<mcp_tools>
  # MCP 工具集成

  ## Sequential Thinking
  use mcp__sequential-thinking__sequentialthinking
  用于：分解复杂问题、多步推理

  ## Context7
  use mcp__context7__resolve-library-id
  use mcp__context7__get-library-docs
  用于：查询最新库文档
</mcp_tools>

<context>
  # 项目上下文

  ## SoT 裁判链
  1. STATE_MACHINE.md v2.8
  2. DATA_SCHEMA.md v5.6
  ...

  ## 项目路径
  - repo_root: ...
  - backend_dir: ...
</context>

<constraints>
  # 约束系统

  ### 🔴 Layer 1: 安全约束
  {安全约束}

  ### 🟡 Layer 2: 行为约束
  {行为约束}

  ### 🟢 Layer 3: 任务约束
  {任务约束}
</constraints>

<workflow>
  ## Sequential Thinking 工作流
  Step 1-6...
</workflow>

<delegation>
  执行链：{Agent 链}
  ...
</delegation>

<execution>
  1. 使用 sequential-thinking 进行顺序化思考
  2. 按 Agent 链顺序执行
  3. 需要查文档时使用 context7
  4. Verify 失败则回到 Execute 修复

  **记住：做得越少，错得越少。**
</execution>

<acceptance_criteria>
  - [ ] 所有测试通过
  - [ ] API 合同未变更
  - [ ] 每个 patch ≤ 5 文件、≤ 200 行
</acceptance_criteria>
```

</output_template>

<example>
  <input>研究 FastAPI 最佳实践</input>
  <output>
    任务类型: research
    行为模式: deep-research
    MCP 工具: [sequential-thinking, context7]
    子代理链: research
  </output>
</example>

<example>
  <input>修复充值状态转换的 bug</input>
  <output>
    任务类型: bugfix
    行为模式: implementation
    MCP 工具: []
    子代理链: explore → execute → verify
  </output>
</example>

<version_history> ### v4.0 (2025-12-18) - MCP 工具集成 整合 SuperClaude Framework: - ✅ sequential-thinking MCP 工具 - ✅ context7 MCP 工具 - ✅ 7 种 Behavioral Modes - ✅ Sequential Thinking 6 步工作流 - ✅ Research Agent (深度研究)

### v3.0 (2025-12-18) - 约束驱动重构
- 约束三层模型: Security → Behavior → Task
- 先读后改原则
- 极简主义约束
- 模块化委托

### v2.1 (2025-12-18)
- 修复 6 个问题

### v1.0 (2025-12-18)
- 初始版本

</version_history>

核心类: PromptStructurer
主入口: structure_prompt(user_request) -> Dict

使用方式:
```python
from agents.skills.prompt_structurer import structure_prompt

result = structure_prompt("重构后端代码")
print(result["rendered_prompt"])
```