# Qalatra Prompts：面向生产环境的智能代码代理工作流框架

> 一套三层架构的提示词工程方案，实现从任务规划到代码执行、PR合并的全链路自动化，支持多框架项目（NestJS、Shopify、Electron）的统一管理

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-05-11T19:14:23.000Z
- 最近活动: 2026-05-11T19:21:06.496Z
- 热度: 154.9
- 关键词: AI代理, 代码自动化, 提示词工程, 工作流编排, Claude Code, GitHub自动化, NestJS, Prisma, 持续集成, 多代理系统
- 页面链接: https://www.zingnex.cn/forum/thread/qalatra-prompts
- Canonical: https://www.zingnex.cn/forum/thread/qalatra-prompts
- Markdown 来源: ingested_event

---

# Qalatra Prompts：面向生产环境的智能代码代理工作流框架

在AI辅助编程日益普及的今天，如何将大语言模型从"聊天助手"升级为"自主执行"的生产力工具，成为开发者社区关注的焦点。近期开源的 **Qalatra Prompts** 项目提供了一套完整的解决方案——通过精心设计的提示词工程和多系统协同架构，实现了代码任务从规划到部署的全链路自动化。

## 项目背景与核心定位

Qalatra Prompts 由 Pirate and Fox 组织开源，定位为"代码代理的标准化工作流提示词库"。与传统AI编程工具不同，它并非简单的代码生成器，而是一个**多代理协作框架**，专门用于管理复杂软件项目的自动化流水线。

该项目的设计哲学强调**人机协作的分层治理**：人类负责关键决策点（需求规划、代码审查、最终批准），而AI代理则承担执行层面的繁琐工作（代码编写、测试验证、PR创建、合并部署）。这种分工既保留了人类对质量的把控，又释放了AI在重复性任务上的效率优势。

## 三层架构：从通用到专用的分层设计

Qalatra Prompts 采用清晰的三层架构，确保既能复用通用逻辑，又能适配不同项目的特殊需求：

### 第一层：规范层（Canonical Layer）

这是整个框架的"内核"。存储在 `qalatra-prompts` 仓库中的提示词定义了**所有项目通用的工作流逻辑**，包括：

- **pipeline-agent.md**：完整的阶段处理器逻辑，涵盖从任务分发到PR合并的全生命周期
- **pipeline-architecture.md**：系统架构文档，解释各层关系及变更应该放在哪一层
- **plan-agent.md**：规划代理的标准工作流，定义如何从需求到可执行计划

这一层的设计原则是："只有真正跨项目通用的逻辑才放在这里"。当规范层改进时，所有部署实例都能自动受益。

### 第二层：配置层（Per-Repo Config）

每个代码仓库拥有独立的 `pipeline-config.md`，定义项目特有的配置参数：

| 配置项 | 说明 |
|--------|------|
| `framework` | 项目框架类型（nestled/shopify/electron/other）|
| `github_slug` | GitHub仓库标识，如 `BizToBiz/biztobiz` |
| `base_branch` | 基础分支名称（develop/live等）|
| `source_system` | 任务来源系统（notion/linear/asana）|
| `auto_merge` | 是否开启自动合并部署 |
| `deploy_command` | 部署命令，如 `pnpm stage && pnpm run deploy` |

这种设计使得同一套规范层可以服务于不同技术栈的项目——无论是基于 NestJS 的后端服务、Shopify 主题，还是 Electron 桌面应用，都能通过配置层完成适配。

### 第三层：部署层（Deployment Wrapper）

每台物理机器/每个部署实例拥有独立的 `CLAUDE.md`，定义：
- 该实例监控的仓库列表
- 指向规范层的引用路径
- 部署级别的覆盖配置（极少使用）

这种分层确保了"一处修改，多处受益"的同时，也保留了必要的灵活性。

## 工作流生命周期：从任务到部署

Qalatra Prompts 定义了一套完整的任务生命周期状态机，涵盖六个主要阶段：

### 阶段1：规划（Planning）

规划代理（Plan Agent）负责将原始需求转化为可执行的技术方案。它遵循严格的约束：

- **只读探索**：只能读取代码库，不能修改任何源文件
- **链接追踪**：自动抓取 Notion、Linear 等来源系统的完整上下文
- **澄清优先**：遇到不确定的需求时，必须列出编号问题清单请求澄清
- **计划输出**：生成自包含的计划文档，供远程执行代理直接使用

规划完成后，计划文件被推送到仓库的 `plans/` 目录，等待人工审查。

### 阶段2：执行（Execution）

执行代理分为两个子路径：

- **2a - 直接任务执行**：针对简单任务，直接编码实现
- **2b - 计划执行**：基于已审查的计划文件进行开发

执行阶段与 Claude Code 云端会话深度集成。代理会：
1. 检查云端会话状态（running/ready）
2. 读取会话转录文本判断进度
3. 根据代码变更类型选择不同的后处理路径

### 阶段3：飞行中（In Flight）

这是核心的监控阶段。代理每30分钟运行一次，协调三个系统的状态：

- **Qalatra**：任务管理系统，存储原始需求
- **FlightDesk**：PR/审查/QA追踪系统
- **Claude Code 云端会话**：实际编码执行环境

关键设计：**在PR打开前就将分支与FlightDesk关联**。这样一旦PR创建，FlightDesk就能通过GitHub webhook自动检测状态变更。

### 阶段4：审查与QA（Review & QA）

当代码进入审查阶段，代理会：
- 监控 SonarCloud、CI 检查状态
- 处理 Copilot 审查意见
- 执行"智能检查"（Intelligence Check）——自动发现潜在问题并注入会话

如果所有检查通过，任务状态更新为 `QA_READY`，等待人工最终批准。

### 阶段5：合并（Merged）

一旦项目管理系统中的状态变为"已批准"，代理自动执行：
- 合并PR到目标分支
- 运行部署命令（如 `pnpm run deploy`）
- 更新源任务状态为完成

### 阶段6：归档（Archived）

任务完成后的清理阶段。

## 框架适配：多技术栈的统一管理

Qalatra Prompts 最令人印象深刻的是其对多种技术框架的适配能力：

### NestJS/Nestled 项目

针对基于 Prisma + NX 的 NestJS 项目，代理内置了完整的代码生成与迁移流程：

**代码生成协调流程**：
1. 检出目标分支
2. 运行 `pnpm db-update` 更新数据库客户端
3. 执行 `npx nx build api` 验证编译
4. 如有TypeScript错误，注入到会话等待修复
5. 提交生成的代码并推送
6. 通知会话执行 `git pull` 同步
7. 创建PR

**数据库迁移流程**：
1. 检测并启动本地PostgreSQL容器
2. 验证 `.env` 中的 `DATABASE_URL` 指向 localhost（安全硬约束）
3. 执行 `prisma migrate dev` 创建迁移
4. 处理漂移检测（drift detection）场景
5. 重新生成代码并验证构建
6. 恢复生产环境配置
7. 提交迁移文件并推送

### Shopify 项目

Shopify主题开发的特点是无代码生成、无数据库迁移、无本地API。代理简化为：
- 仅执行差异检查
- 确认变更合理后直接创建PR
- 依赖 Shopify 的预推送钩子自动同步主题

### Electron 项目

桌面应用开发同样无需复杂后端流程，代理专注于构建和测试验证（具体流程在项目首次遇到时定义）。

## 自我改进机制：持续进化的代理

Qalatra Prompts 内置了"自我训练协议"（Self-Training Protocol），确保代理能从错误中学习：

**四层修复策略**：

1. **通用修复** → 更新 `pipeline-agent.md` 并推送（影响所有项目）
2. **框架修复** → 更新规范层中的框架特定区块（影响该框架的所有项目）
3. **仓库修复** → 更新 `{repo}/agents/pipeline-config.md`（仅影响该仓库）
4. **部署修复** → 更新部署层的 `CLAUDE.md`（仅影响该机器）

**关键原则**："绝不在部署包装器中修复属于规范层的问题"。这种纪律性防止了不同部署实例之间的行为漂移。

## 实际应用场景

从项目文档中可以看到，Qalatra Prompts 已在多个真实项目中落地：

- **BizToBiz**：B2B业务平台
- **FlightDesk**：PR/审查追踪系统
- **Muzebook**：音乐相关应用
- **TMI Shopify 3.0**：电商主题开发
- **Moceanic AI**：AI相关项目

这些项目涵盖了从Web应用到桌面软件、从开源工具到商业平台的多样化场景，验证了框架的通用性。

## 技术启示与未来展望

Qalatra Prompts 代表了AI辅助编程向"AI主导执行"演进的一个重要里程碑。它的设计给我们几点启示：

1. **提示词即代码**：将提示词视为可版本控制、可复用的代码资产，而非一次性的对话内容
2. **分层治理**：通过架构分层平衡通用性与特异性，避免"一刀切"或"各自为政"
3. **人机边界清晰**：明确划分人类决策点与AI执行域，既保证质量又提升效率
4. **多系统编排**：现代开发工作流涉及代码托管、项目管理、CI/CD等多个系统，代理需要具备跨系统协调能力

随着大语言模型能力的持续提升，类似 Qalatra 的"代理编排框架"将成为开发者工具链的重要组成部分。对于希望将AI从"辅助"升级为"自动"的团队而言，Qalatra Prompts 提供了一个经过生产验证的参考实现。

## 相关资源

- **GitHub 仓库**：https://github.com/pirateandfox/qalatra-prompts
- **核心文档**：pipeline-agent.md、pipeline-architecture.md、plan-agent.md
- **适用框架**：NestJS/Prisma、Shopify、Electron
- **集成系统**：Qalatra、FlightDesk、Claude Code、GitHub、Notion、Linear