openlogos

OpenLogos

开源的 AI 时代软件研发方法论

OpenLogos 定义研发规范，RunLogos 让规范落地。

---

什么是 OpenLogos？

OpenLogos 是一套开源的软件研发方法论，专为 AI 时代打造，由拥有 20 余年经验的软件研发专家沉淀而成。它将成熟的软件工程方法论编码为可执行的 AI Skills，使开发者能在 AI 编程工具（Cursor、Claude Code、OpenCode 等）中直接使用这套方法论。

核心立场：反 Vibe Coding。 不是一上来就让 AI 写代码，而是分层推进——先搞清楚为什么做，再设计做什么，最后决定如何做。AI 是强大的执行者，但它需要清晰的指令和约束。

核心理念

三层推进模型

WHY  — 为什么做 → 需求文档（用户痛点、竞品分析、功能需求）
WHAT — 做什么   → 产品设计（功能规格、HTML 原型、设计规范）
HOW  — 如何做   → 技术实现（场景建模 → API → DB → 测试编排 → 代码）

每一层的产出是下一层的输入。跳过任何一层都会导致后续工作的歧义指数级增长。

场景驱动 + 测试先行

• 场景驱动：从真实业务场景出发设计技术方案，时序图是场景到技术的桥梁
• 测试先行：写代码之前先设计 API 编排测试用例，编排既是开发规格也是验收标准

AI 的角色

人做决策，AI 做执行。方法论确保 AI 的执行在正确的轨道上。

快速开始

方式一：使用 CLI 工具（推荐）

# 安装
npm install -g @miniidealab/openlogos

# 初始化项目
openlogos init my-project

# 开始开发——按方法论的三层推进模型逐步推进

方式二：手动集成

1. 将 skills/ 目录下的 SKILL.md 文件复制到你的项目中
2. 在 Cursor 中配置 .cursor/rules/ 引用这些 Skills
3. 或在 Claude Code 中通过 CLAUDE.md 引用

方式三：参考可运行示例（桌面小应用）

FlowTask（Tauri） — 侧重 Claude Code 集成演示：

git clone https://github.com/miniidealab/openlogos.git
cd openlogos/examples/flowtask
pnpm install
pnpm tauri dev    # 开发调试；发布构建见示例 README
# 可选：在仓库根构建 CLI 后，于本目录执行 openlogos verify
# cd ../../cli && npm install && npm run build && cd ../examples/flowtask && openlogos verify

轻记账 Money Log（Electron） — 侧重 OpenCode 集成演示：

git clone https://github.com/miniidealab/openlogos.git
cd openlogos/examples/money-log
npm install
npm run dev
# OpenCode 使用说明见 docs/opencode.md

详见 examples/README.md（FlowTask 与 Money Log 对位说明）。

仓库结构

openlogos/
├── spec/           # 核心规范（平台无关）
│   ├── logos.config.schema.json
│   ├── logos-project.md
│   ├── directory-convention.md
│   ├── workflow.md
│   ├── change-management.md
│   ├── agents-md.md
│   └── test-results.md
│
├── skills/         # AI Skills（平台无关的 Markdown 定义）
│   ├── project-init/          # 项目初始化引导
│   ├── prd-writer/            # Phase 1 · 需求文档
│   ├── product-designer/      # Phase 2 · 产品设计
│   ├── architecture-designer/ # Phase 3-0 · 技术架构
│   ├── scenario-architect/    # Phase 3-1 · 场景建模
│   ├── api-designer/          # Phase 3-2 · API 设计
│   ├── db-designer/           # Phase 3-2 · 数据库设计
│   ├── test-writer/           # Phase 3-3a · 测试用例设计
│   ├── test-orchestrator/     # Phase 3-3b · API 编排测试
│   ├── code-reviewer/         # 代码评审
│   ├── change-writer/         # 变更提案填写
│   └── merge-executor/        # 变更合并执行
│
├── cli/            # openlogos CLI 工具
├── docs/           # 用户文档（如 OpenCode 使用指南）
├── plugin/         # Claude Code 原生插件
├── examples/       # 示例项目（flowtask=Claude Code 桌面演示，money-log=OpenCode 桌面演示）
└── website/        # openlogos.ai 官网源码

采用 OpenLogos 后的项目结构

运行 openlogos init 后，所有方法论资产收纳在 logos/ 目录下，对项目结构零侵入：

your-project/
├── AGENTS.md               # AI 指令入口（根目录，AI 工具要求）
├── logos/                   # OpenLogos 方法论资产
│   ├── logos.config.json    # 项目配置
│   ├── logos-project.yaml   # AI 协作索引
│   ├── resources/           # 研发资源文档
│   └── changes/             # 变更提案工作区
└── src/                     # 你的源代码

AI 工具兼容性

OpenLogos Skills 的核心内容是平台无关的 Markdown 文档。只要 AI 工具支持项目级 prompt 注入，就可以使用。

工具	适配方式	状态
Cursor	AGENTS.md + .cursor/rules/	已支持
Claude Code	原生插件（推荐）或 CLAUDE.md	已支持
OpenCode	原生插件（推荐）或 AGENTS.md 兼容模式	已支持
GitHub Copilot	规划中	Phase 1.5
Windsurf	规划中	Phase 1.5

Claude Code 插件（推荐）

Claude Code 用户可以通过原生插件获得最佳体验。插件提供：

• 13 个 AI Skills 自动发现 — Claude 根据任务上下文自动激活正确的 Skill
• 斜杠命令 — 无需切终端，在对话中直接操作
• SessionStart Hook — 每次启动自动检测项目 Phase 并注入上下文
• change-reviewer 代理 — 只读审查变更提案的合规性

安装

# 1. 添加 OpenLogos 插件市场（一次性操作）
/plugin marketplace add miniidealab/openlogos

# 2. 安装插件
/plugin install openlogos@miniidealab-openlogos

可用命令

命令	说明
/openlogos:status	查看当前 Phase 进度和下一步建议
/openlogos:next	获取下一步操作的详细引导和可用提示词
/openlogos:init [name]	初始化新项目（调用 CLI）
/openlogos:sync	重新生成 AI 指令文件和 Skills
/openlogos:change <slug>	创建变更提案
/openlogos:merge <slug>	生成变更合并指令（MERGE_PROMPT.md）
/openlogos:archive <slug>	归档已完成的变更提案
/openlogos:verify	运行测试验收并生成三层追溯报告
/openlogos:launch	激活变更管理（初始开发完成后使用）

工作流示例

1. 启动 Claude Code → SessionStart Hook 自动检测 Phase
2. 输入 /openlogos:next → Claude 告诉你"当前是 Phase 1，建议写需求文档"
3. 说 "帮我写需求文档" → Claude 自动激活 prd-writer Skill，按步骤引导
4. 需求写完后再次 /openlogos:next → 进入 Phase 2 产品设计
5. 逐步推进到 Phase 3（架构 → 场景 → API → 测试 → 代码）
6. 全部完成后 /openlogos:launch → 激活变更管理
7. 后续修改用 /openlogos:change <slug> 创建变更提案

与 CLI 的关系

场景	使用方式
初始化新项目	CLI: openlogos init
查看进度	插件: /openlogos:status 或 CLI: openlogos status
Phase 推进（写文档）	插件: 自动激活 Skill
创建变更提案	插件: /openlogos:change 或 CLI: openlogos change
运行测试验收	CLI: openlogos verify