Superpowering with Files：为本地编码智能体构建可治理的规划与推理工作流框架

一个统一治理框架，将策略转化为多IDE原生指令文件，结合持久化文件规划与可选深度推理层，解决AI编码助手缺乏状态持久化和跨平台一致性的痛点。

随着大型语言模型（LLM）在软件开发中的广泛应用，开发者们开始依赖GitHub Copilot、Cursor、Claude Code和Codex等AI编码助手来提升效率。然而，这些工具在实际使用中暴露出一个核心问题：缺乏持久化的任务状态和跨平台一致的治理机制。

当你在一个复杂的项目中使用AI助手时，会话可能持续数小时甚至数天。但大多数AI编码工具采用"无状态"设计——每次对话都是独立的，上下文窗口有限，且无法在不同会话间保持任务连续性。更糟糕的是，不同IDE（集成开发环境）的AI助手使用各自不同的配置格式和指令系统，导致团队难以建立统一的编码规范和审查标准。

Superpowering with Files是一个开源治理框架，旨在解决上述痛点。它通过一套共享策略，自动生成适用于多种主流AI编码助手的原生指令文件、技能投影和可选的推理工作流钩子。

该项目的核心架构包含两个上游系统的整合：

• planning-with-files：作为唯一的持久化任务记忆系统，负责维护活跃任务状态
• superpowers：作为可选的临时深度推理层，仅在需要复杂分析时启用

这种分层设计既保证了简单任务的执行效率，又为复杂场景保留了深度推理的能力。

框架的核心价值在于"一次定义，多处生效"。开发者只需在仓库中维护一套策略文件，框架会自动将其投影为各IDE所需的格式：

目标平台	工作区入口文件	用户全局入口文件	技能根目录
Codex	AGENTS.md	~/.codex/AGENTS.md	.agents/skills
GitHub Copilot	.github/copilot-instructions.md	~/.copilot/instructions/	.agents/skills
Cursor	.cursor/rules/harness.mdc	Cursor设置中的用户规则	.cursor/skills
Claude Code	CLAUDE.md	~/.claude/CLAUDE.md	.claude/skills

这种投影机制确保了无论团队成员使用何种AI编码工具，都能遵循相同的代码规范、审查流程和安全策略。

框架要求所有被跟踪的任务必须使用planning/active/<task-id>/目录结构来维护状态。该目录包含三个关键文件：

• task_plan.md：活跃计划、阶段划分和生命周期管理
• findings.md：持久化的发现结果和约束条件
• progress.md：会话日志、检查点和变更文件记录

当任务完成并通过生命周期检查后，相关文件会被归档到planning/archive/<timestamp>-<task-id>/，形成完整的历史追溯链。

对于需要复杂分析的场景，框架允许临时启用superpowers作为推理层。其工作流程如下：

任务到达 → 读取Harness入口文件 → 是否简单明确？
  ├─ 是 → 直接执行 → 验证 → 报告结果
  └─ 否 → 创建/复用planning/active/<task-id>/ → 以Planning with Files为真相源
       → 是否需要深度推理？
         ├─ 是 → 临时使用Superpowers → 将决策同步回规划文件 → 验证 → 报告结果
         └─ 否 → 保持正常执行模式 → 验证 → 报告结果

这种设计的关键在于superpowers只是临时的推理层，其详细计划存储在docs/superpowers/plans/<task-id>.md，并在推理完成后将关键决策同步回持久化的规划文件。这避免了深度推理模型的高成本和延迟对日常开发的影响。

框架提供了可选的safety配置文件，为高风险或长时间运行的AI会话增加额外的安全边界：

• 路径边界检查：防止AI助手意外修改敏感文件或越权访问
• 自动检查点：在执行高风险操作前自动创建代码快照
• 工作流优先模式：强制要求使用独立的工作目录进行实验性修改

安全相关的CLI命令包括：

# 工作流预检（带安全检查）
./scripts/harness worktree-preflight --task <task-id> --safety

# 创建检查点
./scripts/harness checkpoint-push --message="关键修改前的备份"

对于开发团队而言，Superpowering with Files解决了几个实际问题：

1. 知识沉淀：AI助手的推理过程和关键决策被持久化到文件中，新成员可以通过阅读planning目录快速理解项目历史和决策依据

2. 跨平台一致性：无论使用Cursor、Copilot还是Claude Code，团队都能执行相同的代码规范和审查流程

3. 成本优化：简单任务直接执行，仅在必要时启用昂贵的深度推理模型，有效控制API调用成本

4. 可审计性：完整的任务生命周期记录（从创建到归档）满足了企业级项目对可追溯性的要求