快速开始
让你的第一个 OpenLogos 项目跑起来——从安装到生成第一份 AI 需求文档。
所需时间: 约 10 分钟
- Node.js >= 18
- 一个 AI 编码工具 —— 以下之一:
- Claude Code(基于终端)
- OpenCode(基于终端)
- Codex CLI(基于终端)
- Cursor(内置 AI 的 IDE)
- ZCode、Qoder CLI 或 WorkBuddy(以项目插件形式接入)
第 1 步:安装
Section titled “第 1 步:安装”npm install -g @miniidealab/openlogos验证安装——本指南基于 0.16.0 编写:
openlogos --version第 2 步:初始化项目
Section titled “第 2 步:初始化项目”运行 init 命令——它会让你选择语言和 AI 工具:
选项 7~9 分别对应 ZCode、Qoder 和 WorkBuddy。当你希望一个项目同时部署所有支持的目标(Claude Code、OpenCode、Codex、Cursor、ZCode、Qoder、WorkBuddy)时,选择 All。下面的输出有删节;另外几行(例如检测到技术栈时的忽略目录建议、verify.pre_run_command 提醒)是否出现取决于你的目录。
如需跳过交互(例如在脚本或 CI 中),同时传入两个参数:
openlogos init my-project --locale zh --ai-tool cursor--ai-tool 可取 claude-code、opencode、codex、cursor、zcode、qoder、workbuddy、other 或 all。非交互模式下必须提供 --locale。
openlogos init my-project
Choose language / 选择语言: 1. English (default) 2. 中文
Your choice [1/2] (default: 1): 1
Choose AI coding tool / 选择 AI 编码工具: 1. Claude Code (default) 2. OpenCode 3. Codex 4. Cursor 5. Other 6. All (deploy for all tools)
7. ZCode 8. Qoder 9. WorkBuddy
Your choice [1/2/3/4/5/6] (default: 1): 1
Creating OpenLogos project structure for "my-project"...
✓ logos/resources/prd/1-product-requirements/ ✓ logos/resources/prd/2-product-design/1-feature-specs/ ✓ logos/resources/prd/2-product-design/2-page-design/ ✓ logos/resources/prd/3-technical-plan/1-architecture/ ✓ logos/resources/prd/3-technical-plan/2-scenario-implementation/ ✓ logos/resources/api/ ✓ logos/resources/database/ ✓ logos/resources/test/ ✓ logos/resources/scenario/ ✓ logos/resources/verify/ ✓ logos/changes/ ✓ logos/changes/archive/ ✓ logos/logos.config.json ✓ logos/logos-project.yaml ✓ AGENTS.md ✓ CLAUDE.md ✓ 17 skills deployed to logos/skills/ ✓ Claude Code plugin deployed: 10 commands, 1 agents → .claude/ ✓ 24 specs deployed to logos/spec/
Project initialized. Next steps: 1. Review logos/logos.config.json to verify project settings 2. Start with Phase 1: tell AI "Help me write requirements" 3. Run `openlogos status` to check progress at any timeinit 会把 Claude Code 命令、change-reviewer agent 和 hooks(SessionStart 上下文、PreToolUse 写入门禁、执行后检查)直接写入项目的 .claude/ 目录,无需另行安装插件。
openlogos init my-project
Choose language / 选择语言: 1. English (default) 2. 中文
Your choice [1/2] (default: 1): 1
Choose AI coding tool / 选择 AI 编码工具: 1. Claude Code (default) 2. OpenCode 3. Codex 4. Cursor 5. Other 6. All (deploy for all tools)
7. ZCode 8. Qoder 9. WorkBuddy
Your choice [1/2/3/4/5/6] (default: 1): 2
Creating OpenLogos project structure for "my-project"...
✓ logos/resources/prd/1-product-requirements/ ✓ logos/resources/prd/2-product-design/1-feature-specs/ ✓ logos/resources/prd/2-product-design/2-page-design/ ✓ logos/resources/prd/3-technical-plan/1-architecture/ ✓ logos/resources/prd/3-technical-plan/2-scenario-implementation/ ✓ logos/resources/api/ ✓ logos/resources/database/ ✓ logos/resources/test/ ✓ logos/resources/scenario/ ✓ logos/resources/verify/ ✓ logos/changes/ ✓ logos/changes/archive/ ✓ logos/logos.config.json ✓ logos/logos-project.yaml ✓ AGENTS.md ✓ CLAUDE.md ✓ 17 skills deployed to logos/skills/ ✓ OpenCode plugin deployed to .opencode/plugins/openlogos.js + opencode.json ✓ opencode.json created with recommended permission defaults ✓ OpenCode slash commands deployed to .opencode/commands/ (10 files) ✓ 24 specs deployed to logos/spec/
Project initialized. Next steps: 1. Review logos/logos.config.json to verify project settings 2. Start with Phase 1: tell AI "Help me write requirements" 3. Run `openlogos status` to check progress at any timeopenlogos init my-project
Choose language / 选择语言: 1. English (default) 2. 中文
Your choice [1/2] (default: 1): 1
Choose AI coding tool / 选择 AI 编码工具: 1. Claude Code (default) 2. OpenCode 3. Codex 4. Cursor 5. Other 6. All (deploy for all tools)
7. ZCode 8. Qoder 9. WorkBuddy
Your choice [1/2/3/4/5/6] (default: 1): 4
Creating OpenLogos project structure for "my-project"...
✓ logos/resources/prd/1-product-requirements/ ✓ logos/resources/prd/2-product-design/1-feature-specs/ ✓ logos/resources/prd/2-product-design/2-page-design/ ✓ logos/resources/prd/3-technical-plan/1-architecture/ ✓ logos/resources/prd/3-technical-plan/2-scenario-implementation/ ✓ logos/resources/api/ ✓ logos/resources/database/ ✓ logos/resources/test/ ✓ logos/resources/scenario/ ✓ logos/resources/verify/ ✓ logos/changes/ ✓ logos/changes/archive/ ✓ logos/logos.config.json ✓ logos/logos-project.yaml ✓ AGENTS.md ✓ CLAUDE.md ✓ Cursor assets installed: <N> skills + <N> commands + 1 subagent, hooks (sessionStart, beforeShellExecution, afterShellExecution, afterFileEdit); start a new Cursor session to load refreshed skills and hooks ℹ Guard strength on Cursor (IDE and cursor-agent CLI) is partial: shell commands get a light pre-check via beforeShellExecution (guard-scope changes need host approval) plus an afterShellExecution post-check; file edits are only reported after the fact via afterFileEdit and are never blocked beforehand. OpenLogos does not wire preToolUse, so Cursor is not equivalent to claude-code. ✓ 24 specs deployed to logos/spec/
Project initialized. Next steps: 1. Review logos/logos.config.json to verify project settings 2. Start with Phase 1: tell AI "Help me write requirements" 3. Run `openlogos status` to check progress at any timeCursor 输出中的 <N> 表示实际部署到 .cursor/skills/ 的 Skill 与命令 Skill 数量(中文 locale 下这一行为「Cursor 三件套已安装:……」)。选择 ZCode、Qoder 或 WorkBuddy 时,OpenLogos 插件分别安装到 .zcode/plugins/openlogos/、.qoder/plugins/openlogos/ 或 .workbuddy/plugins/openlogos/;之后请在对应工具中新建 session,使插件快照生效。
现在进入项目并查看状态:
cd my-projectopenlogos status📊 OpenLogos Project Status
──────────────────────────────────────────────────🔲 Phase 1 · Requirements (WHY)🔲 Phase 2 · Product Design (WHAT)🔲 Phase 3-0 · Architecture🔲 Phase 3-1 · Scenario Modeling🔲 Phase 3-2 · API Design🔲 Phase 3-2 · Database Design🔲 Phase 3-3 · Deployment Plan🔲 Phase 3-4a · Test Case Design (Unit + Scenario)🔲 Phase 3-4b · API Orchestration Tests🔲 Phase 3-5 · Code Implementation🔲 Phase 3-6 · Test Acceptance (verify)🔲 Phase 3-7 · Deployment Execution🔲 Phase 3-8 · Deployment Smoke Test──────────────────────────────────────────────────
💡 Suggested next step: Phase 1 · Requirements (WHY) → Tell AI: "Help me write requirements"一切都是空的——这是预期的。方法论会引导你按顺序走完每个阶段。
第 3 步:在你的 AI 工具中打开
Section titled “第 3 步:在你的 AI 工具中打开”在你选择的 AI 工具中打开项目。说一句类似 “请帮我看看这个项目” 的话——AI 会自动检测到 OpenLogos 并向你展示项目状态。
在终端中进入项目并启动 Claude Code:
cd my-projectclaudeClaude Code 在启动时读取 AGENTS.md,自动检测到这是一个 OpenLogos 项目:

它会展示完整的推进路径,并将 Phase 1 标记为起点,提示 “Empty — START HERE”。
进入项目并启动 OpenCode:
cd my-projectopencodeOpenCode 读取项目配置并显示一份详细的概览:

它会展示项目结构、检测当前阶段,甚至准确告诉你需要回答哪些问题才能开始。
在 Cursor 中打开 my-project 文件夹(或在其中运行 cursor-agent)。OpenLogos Skills 从 .cursor/skills/ 加载(显式命令以 /openlogos-<command> 触发),change-reviewer subagent 从 .cursor/agents/ 加载,hooks 从 .cursor/hooks.json 加载——无需手动配置。如果 Cursor 已经打开,请在 init 或 sync 之后新建 session。
Cursor 下的写入门禁为部分强度:shell 命令有事前轻判(beforeShellExecution)和执行后检查(afterShellExecution);文件编辑只在事后报告(afterFileEdit)。详见 PreToolUse Guard。
让 AI 审阅项目,它就会向你展示完整的阶段推进:

AI 检测出所有阶段,展示每一步对应的目录,并建议从 Phase 1 开始。
在 my-project 目录中新建该工具的 session。.zcode/plugins/openlogos/、.qoder/plugins/openlogos/ 或 .workbuddy/plugins/openlogos/ 下的 OpenLogos 插件提供 Skills、命令和 agent;它的 SessionStart hook 注入当前阶段,PreToolUse hook 执行写入门禁。init 还会把宿主专属指令写入根 AGENTS.md 的 OpenLogos 托管区块。
让 AI 审阅项目,它会展示阶段推进并建议从 Phase 1 开始。
第 4 步:你的第一次 AI 协作
Section titled “第 4 步:你的第一次 AI 协作”关键时刻到了。告诉 AI:
“帮我写需求文档”
AI 加载 prd-writer Skill,并向你提出三个问题:

- 你想构建什么产品?(一句话:它是什么、给谁用、解决什么问题?)
- 目标用户是谁?(尽可能具体——描述一个真实的人)
- 核心目标是什么?(产品应该达成什么,你会如何衡量成功?)
哪怕只有一个粗略的想法也可以回答——例如:
“给普通用户用的计算器,简洁又好看”
AI 接收你简短的输入,提出几个跟进性的澄清问题,然后产出一份完整、结构化的需求文档:

大约 2 分钟内,它生成了一份 229 行的需求文档,包含:
- 产品定位和核心目标
- 目标用户画像
- 痛点分析(P01–P04)
- 4 个场景(S01–S04)及其优先级
- 每个场景完整的 GIVEN/WHEN/THEN 验收标准
- 约束、边界,以及一份”不做清单”
文档被保存到 logos/resources/prd/1-product-requirements/01-requirements.md——并且可以立即查看:

第 5 步:查看进度
Section titled “第 5 步:查看进度”现在运行 status 命令(或在 Claude Code 中使用斜杠命令):

Phase 1 被标记为 Done。AI 确认:
- ✅ 需求文档(
01-requirements.md)已就位,包含 4 个场景(S01–S04) - 👉 下一步:Phase 2 · 产品设计(WHAT) —— 只需说 “基于需求做产品设计”
你已经完成了 OpenLogos 方法论的第一个完整循环。后续每个阶段的运作方式都一样:AI 读取上一阶段的产出,加载合适的 Skill,并引导你走下一步。
接下来做什么?
Section titled “接下来做什么?”你现在有了一个可用的 OpenLogos 项目,以及一份完整的需求文档。从这里你可以: