quick-question

---

✅ Verified path: Claude Code + Unity 2021.3+ on macOS or Windows. Daily-driven, end-to-end battle-tested. This is the recommended setup if you want everything in this README to "just work".

🧪 Experimental — contributions welcome: Godot, Unreal, and S&box adapters ship as scaffolds. The bridge code, command surface, and CI smoke tests are in place, but no one has yet shipped a real game using any non-Unity adapter — they have not been validated in actual development use. Same caveat for non-Claude hosts (Codex CLI, Cursor, Continue, other MCP hosts): the runtime is agent-agnostic by design, but the verified loop is Claude Code-only. If you're building with one of these, your bug reports and PRs are how the adapter graduates to "verified" — see CONTRIBUTING.md.

Why qq

AI agents can write code. They cannot, by default, tell you whether the code compiles, the tests pass, the behavior is right, or whether they just produced 500 lines of plausible-looking nonsense. In a game project — where "running" means the editor opens, the scene loads, and frame N+1 looks like you wanted — that gap is the entire problem.

quick-question is the runtime layer that closes it. Four work modes — prototype, feature, fix, hardening — are first-class state, not flavor text. A prototype keeps the compile green and stays playable; a hardening pass forces tests, review, and document/code consistency before shipping. The artifact-driven controller (/qq:go) reads .qq/state/*.json and your work_mode, then recommends the concrete next skill — instead of guessing from chat history.

The runtime is engine-symmetric and agent-agnostic. Unity has the deepest integration: compile and test drive the open Editor through the official Unity CLI (unity command / unity job). Godot, Unreal, and S&box are at runtime parity through Python bridges. Claude Code gets 28 skills, auto-compile hooks, and review gates. Codex, Cursor, Continue, and any MCP-compatible host get the same underlying runtime through MCP and plain scripts. Structured state in .qq/ is plain JSON on disk — readable by any agent, across sessions.

The methodology is grounded in the document-first approach described in AI Coding in Practice: An Indie Developer's Document-First Approach.

How it works

Edit .cs/.gd/.cpp file
  → Hook auto-compiles via qq-compile.sh
    → Result + error context written to .qq/state/
      → /qq:go reads state, recommends next skill
        → Skill runs, writes new state
          → Loop

Four layers cooperate:

• Hooks fire on every Claude Code tool call. PostToolUse compiles after Edit/Write on engine source files via qq-compile.sh (the multi-engine dispatcher). PreToolUse blocks edits during review verification, or after a red compile, until the relevant gate clears. Stop blocks session end if skills were modified without /qq:self-review. All gate files are keyed by the Claude Code session id, so concurrent sessions never block each other.
• Controller — /qq:go reads .qq/state/*.json, recent run records, your work_mode, and the active policy_profile, then routes to the next skill. It is a controller, not an implementation engine — it only falls back to context heuristics when state is ambiguous.
• Engine bridges — the official Unity CLI for Unity (tykit only as a fallback in projects that still have it), godot_bridge.py, unreal_bridge.py, sbox_bridge.py. Compile, test, console, find / inspect — verified execution, not blind file writes.
• Runtime data — .qq/runs/*.json (raw run logs), .qq/state/*.json (latest compile / test state), .qq/state/session-decisions.json (cross-skill decision journal), .qq/telemetry/. Plain JSON, readable by any agent across sessions.

For code review, two symmetric modes share the same verification loop: Codex review (code-review.sh → codex exec, cross-model) and Claude review (claude-review.sh → claude -p, single-model). Each produces findings, then independent verification subagents check every finding against actual source and flag over-engineering — up to 5 rounds until clean. The unified review gate (scripts/hooks/review-gate.sh) blocks edits until all verification subagents complete (three-field format: <ts>:<completed>:<expected>). MCP exposes one-shot qq_code_review and qq_plan_review tools for non-Claude hosts.

See Architecture Overview, Hook System, Cross-Model Review, and Worktrees for layer-by-layer detail.

Engines

Engine	Compile	Test	Editor control	Bridge
Unity 2021.3+ ✅ verified	official Unity CLI (unity command recompile) / tykit / refresh trigger	EditMode + PlayMode	official Unity CLI	qq_mcp.py (qq_* tools)
Godot 4.x 🧪 preview	GDScript check via headless editor	GUT / GdUnit4	Editor addon	godot_bridge.py
Unreal 5.x 🧪 preview	UnrealBuildTool + editor commandlet	Automation tests	Editor command (Python)	unreal_bridge.py
S&box 🧪 preview	dotnet build	Runtime tests	Editor bridge	sbox_bridge.py

Unity is the verified path — daily-driven through the official Unity CLI against an open Editor (see Unity Editor channel). Godot, Unreal, and S&box ship as experimental scaffolds: the adapter code, bridge surfaces, and CI smoke tests are in place, but no one has yet built a real game on top of any non-Unity adapter. Treat them as starting points for contributors, not as production-ready paths — see CONTRIBUTING.md.

Install

Requirements

• macOS or Windows (Windows needs Git for Windows for bash + core utilities)
• Engine: Unity 2021.3+ / Godot 4.x / Unreal 5.x / S&box
• python3 (required), jq (recommended — hook scripts fall back to python3 when jq is missing)
• Claude Code for the full skill + hook experience
• Codex CLI (optional — enables cross-model review)

Install the runtime

All agents share the same runtime install. It auto-detects your engine and writes scripts, bridges, and config into the project.

git clone https://github.com/tykisgod/quick-question.git /tmp/qq
/tmp/qq/install.sh /path/to/your-project          # auto-detect engine
/tmp/qq/install.sh --wizard /path/to/your-project  # interactive wizard
/tmp/qq/install.sh --preset quickstart /path/to/your-project  # one-shot preset
rm -rf /tmp/qq

Available presets: quickstart (minimal), daily (recommended), stabilize (full checks for release prep). Use --profile, --modules, --without for fine-grained control.

Connect your agent

Agent	Setup	What you get
Claude Code	/plugin marketplace add tykisgod/quick-question/plugin install qq@quick-question-marketplace	All 28 /qq:* slash commands, auto-compile hooks, review gates, MCP — full experience
Codex CLI	python3 ./scripts/qq-codex-mcp.py install --pretty	Project-local MCP bridge; use qq-codex-exec.py to pin the working root
Cursor / Continue / other MCP hosts	Add qq to mcpServers in your host config: command: python3, args: ["./scripts/qq_mcp.py"], cwd: /path/to/project	Compile, test, policy check, project state, and review as qq_* MCP tools; Godot, Unreal, and S&box add their editor bridge tools — see docs/dev/agent-integration.md
Any shell	Run ./scripts/qq-compile.sh / ./scripts/qq-test.sh from the project root	The same compile and test path the hooks use; for other Unity Editor queries use the official Unity CLI — see shared/unity-cli-reference.md

For non-Unity engines, call the bridge scripts directly (e.g. python3 ./scripts/godot_bridge.py compile).

Quick start

80/20 principle. qq has 28 commands but most of the value comes from 4. This section is the fastest path to ROI — learn the 20% that matters, ignore the rest until you actually need it.

Step 1 — Set your default work mode

work_mode controls how strict the workflow is. Pick the lightest mode that fits the task; escalate later only when needed.

Mode	When	What it does
prototype	Trying ideas, gray-box, fun check	Compile-green only. Skips formal docs and review.
feature ⭐	Default for normal feature work	Plan + execute + test + targeted review. Balanced.
fix	Reproducing and fixing a known bug	Repro first, smallest safe fix, regression test.
hardening	Pre-merge, pre-release, risky refactor	Tests + review + doc-drift + best-practice. The strict gate.

Set it once in .qq/local.yaml:

work_mode: feature

The most common new-user mistake is leaving the project on hardening by default, then complaining qq is "too noisy". Stay in feature and only flip to hardening at merge time.

Step 2 — Learn one loop, not 28 commands

For 90% of tasks this is all you need:

/qq:go "what you want to do"   # picks the right next step from .qq/state + work_mode
/qq:execute                     # implement (auto-compile on every .cs edit)
/qq:test                        # run tests + scrape runtime errors from Editor.log
/qq:best-practice               # quick anti-pattern + perf scan

/qq:go is the adaptive entry point — it reads .qq/state and your work_mode, then routes to the right skill. For clear tasks, jump straight to /qq:execute. For vague ones, let /qq:go route you through /qq:design → /qq:plan first.

The auto-compile hook is what makes this worth the setup: every .cs edit triggers compile, and the compile gate blocks further edits while compilation is red until you fix it. The single biggest time sink the loop kills is "I think it builds — let me find out tomorrow".

Step 3 — Three templates that cover most work

Feature development

/qq:go "add a fatigue recovery system to crew"
/qq:execute
/qq:test
/qq:best-practice

Bug fix (qq enters fix mode → repro → minimal patch → regression test)

/qq:go "fix the harbor docking bug, repro first"
/qq:execute
/qq:test

Pre-merge gate (only when you're about to push or PR)

/qq:best-practice
/qq:claude-code-review        # or /qq:codex-code-review for cross-model
/qq:doc-drift
/qq:test
/qq:commit-push

Step 4 — What to skip in your first week

Resist using these until the basic loop above is predictable:

• /qq:bootstrap — wait until you trust the loop
• Heavy doc ceremony (/qq:design → /qq:plan → /qq:doc-drift for every task) — only use design/plan when the task is genuinely vague. They're not a tax.
• Cross-model review on every change — save /qq:codex-code-review for merge gates or large refactors. It's 5–10 min per round; running it after every small edit kills the rhythm.
• /qq:go --auto — end-to-end automation works, but build trust in manual runs first
• Custom profiles / packs / module switching — defaults are fine for week one

Step 5 — Customize CLAUDE.md as real guardrails

Install copies a CLAUDE.md template to your project. Replace the boilerplate with 5–8 hard rules that match your project, not an essay. Example rules for a Unity game project:

• Runtime logic must not use reflection
• Do not modify UI / prefab names / inspector fields unless asked
• No GetComponent / FindObjectOfType in Update / FixedUpdate paths
• After editing .cs, must verify compile-green before reporting "done"
• Prefer existing patterns; do not invent a second framework
• No abstraction layers for hypothetical future requirements

This is the single highest-ROI customization — it cuts the rate at which the model "gets clever" in the wrong direction.

Two warnings

1. Don't read raw .qq/runs/*.json logs in your prompts. They're operational telemetry, not context. Use qq-project-state.py --pretty for the structured snapshot when you actually need state.
2. Don't run cross-model review after every small edit. It makes the loop feel slow and you'll start hating qq for the wrong reason. Reserve it for merge gates and large refactors.

Success check (week 1)

After a week, ask yourself:

1. Did manual "back to Unity to check compile" trips drop noticeably?
2. Did "AI says done but it isn't" rework drop?
3. Did mid-size feature wrap-up time get shorter?
4. Did review-gate ceremony start feeling annoying?

If 1–3 improved and 4 is tolerable, scale up. If 4 dominates, drop the project to feature or prototype and only flip to hardening at merge time — that's exactly what the profile system is designed for.

→ Deeper walkthroughs: Getting Started · Configuration · Worktrees

Commands

Workflow

Command	Description
/qq:go	Detect workflow stage, recommend next step
/qq:bootstrap	Decompose a game vision into epics, orchestrate full pipeline for each
/qq:design	Write a game design document
/qq:plan	Generate technical implementation plan
/qq:execute	Smart implementation with auto-compile verification

Testing

Command	Description
/qq:add-tests	Author EditMode, PlayMode, or regression tests
/qq:test	Run tests and check for runtime errors

Code review

Command	Description
/qq:codex-code-review	Cross-model: Codex reviews, Claude verifies (max 5 rounds)
/qq:codex-plan-review	Cross-model plan / design review
/qq:claude-code-review	Claude-only deep code review with auto-fix loop
/qq:claude-plan-review	Claude-only plan / design review
/qq:best-practice	Quick scan for anti-patterns and performance issues
/qq:self-review	Review recent skill / config changes
/qq:post-design-review	Review a design doc from implementer's perspective — check consistency, buildability, codebase gaps

Analysis

Command	Description
/qq:brief	Architecture diagram + PR review checklist vs base branch
/qq:timeline	Commit history grouped into semantic phases
/qq:full-brief	Run brief + timeline in parallel
/qq:deps	Analyze .asmdef dependencies (Mermaid graph + matrix)
/qq:doc-drift	Compare design docs against actual code
/qq:doc-sync	Reconcile drifted docs — detect, draft fixes, land only what you approve

Utilities

Command	Description
/qq:commit-push	Batch commit and push
/qq:explain	Explain module architecture in plain language
/qq:grandma	Explain concepts using everyday analogies
/qq:tech-research	Search open-source communities for technical solutions
/qq:record	Record captioned review videos and screenshot sets of the running game, self-check them, and build a review page
/qq:design-research	Search for game design references and patterns
/qq:changes	Summarize all changes from the current session
/qq:doc-tidy	Scan and recommend documentation cleanup

Work modes

Mode	When	Must do	Usually skip
prototype	New mechanic, greybox, fun check	Keep compile green, stay playable	Formal docs, full review
feature	Building a retainable system	Design, plan, compile, targeted tests	Full regression on every change
fix	Bug fix, regression repair	Reproduce first, smallest safe fix	Large refactors
hardening	Risky refactor, release prep	Tests, review, doc / code consistency	Prototype shortcuts

Set the shared default in qq.yaml. Override per-worktree in .qq/local.yaml. work_mode and policy_profile are independent: the first answers "what kind of task is this?", the second answers "how much verification does this project expect?". A prototype and a hardening pass can share the same policy profile, or not. See Configuration for the full reference.

Configuration

Three files control qq's behavior in your project:

• qq.yaml — runtime config: work_mode, policy_profile, trust_level, workflow (Heavy Review / Prototype Loop), module selection. Built-in profiles: lightweight, core, feature, hardening. See templates/qq.yaml.example.
• CLAUDE.md — coding standards and compile verification rules scoped to your project. See templates/CLAUDE.md.example.
• AGENTS.md — architecture rules and review criteria for subagent workflows. See templates/AGENTS.md.example.

Unity Editor channel

qq reaches an open Unity Editor through the official Unity CLI (unity command / unity job), which talks to Unity's Pipeline server (package com.unity.pipeline). When a project has a live Library/Pipeline/.unity-pipeline-port and the unity CLI is found (on PATH, or wherever QQ_UNITY_CLI points), auto-compile runs unity command recompile, which works while Unity is unfocused or minimized and never brings its window forward, and /qq:test submits EditMode runs as detached jobs and PlayMode runs asynchronously, taking green or red from the test summary rather than from any success field.

python3 ./scripts/qq-unity-cli.py channel --project .   # which channel this project uses: unity-cli, tykit, or none

Never print Library/Pipeline/.unity-pipeline-port: it holds a token that grants arbitrary C# execution inside the Editor, and qq reads only its port / pid / projectPath. When no live Editor is found, compile and test exit 2 instead of starting a batch-mode Unity that would fight the open Editor for the project lock; batch mode runs only with an explicit --batch. See shared/unity-live-state.md, shared/unity-cli-reference.md, and Hook System.

tykit. qq no longer installs tykit (the in-Editor HTTP server in packages/com.tyk.tykit/) or its Python and MCP bridges. Projects that still have tykit keep working: the compile and test scripts fall back to it when there is no usable official CLI channel. The package also works on its own, without qq; see docs/en/tykit-api.md.

FAQ

Does this work on Windows? Yes. Requires Git for Windows for bash, curl, and core utilities. The 1.15.x and 1.16.x releases hardened Windows support — LF line endings via .gitattributes, path normalization, Python Store-alias detection, and a jq fallback in hook scripts.

Do I need Codex CLI? No. Codex CLI enables cross-model review (/qq:codex-code-review), but /qq:claude-code-review works without it.

Can I use this with Cursor / Copilot / Codex / other agents? Yes. The runtime layer (engine bridges, .qq/ state, scripts) is agent-agnostic — anything that can run a shell command or speak MCP can use it. The 28 /qq:* slash commands and auto-compile hooks are Claude Code-specific, but the underlying scripts they call are ordinary shell and Python. See docs/dev/agent-integration.md.

What happens when compilation fails? The auto-compile hook captures the error output and surfaces it in the conversation. Until the compile recovers, the compile gate blocks edits to other engine source files. The files with errors, and the file whose edit broke the build, stay editable. The agent reads the errors, fixes those files (or reverts the change), and the hook compiles again automatically.

Can I use tykit without quick-question? Yes. Add the UPM package from packages/com.tyk.tykit/. See the tykit README.

Which Unity versions are supported? The official Unity CLI channel needs a Unity Editor that runs the Pipeline server (package com.unity.pipeline). Projects without it can keep tykit as their Editor channel; tykit requires Unity 2021.3+. MCP alternatives: mcp-unity requires Unity 6+; Unity-MCP has no version requirement.

---

✅ 已验证路径：Claude Code + Unity 2021.3+，macOS 或 Windows。每天实战、端到端经过验证。这是想让 README 里所有内容"开箱即用"时的推荐配置。

🧪 实验性 — 欢迎贡献：Godot、Unreal、S&box 适配器目前只是脚手架。桥接代码、命令接口和 CI smoke test 都到位了，但还没有人用任何非 Unity 适配器实际开发过游戏——它们没有经过真实开发场景的验证。非 Claude 宿主（Codex CLI、Cursor、Continue 等其他 MCP 宿主）同理——运行时的设计是 agent 无关的，但已验证的工作流仅限 Claude Code。如果你正在用其中之一开发，你的 bug 报告和 PR 就是该适配器晋级到"已验证"的路径——参见 CONTRIBUTING.md。

为什么选 qq

AI agent 能写代码。但默认情况下，它告诉不了你代码能不能编译、测试有没有过、行为对不对，或者它是不是刚写了 500 行貌似合理的废话。在游戏项目里——"运行起来"意味着编辑器打开、场景加载、第 N+1 帧看起来跟你想的一样——这个鸿沟就是问题的全部。

quick-question 是把这个鸿沟闭合掉的运行时层。四种工作模式 prototype、feature、fix、hardening 是一等公民状态，不是装饰文字。原型模式保持编译绿灯、保持可玩；加固模式在发版前强制测试、审阅和文档/代码一致性。artifact 驱动的控制器 /qq:go 读取 .qq/state/*.json 和你的 work_mode，然后推荐具体的下一个 skill——而不是从聊天历史里靠猜。

运行时是引擎对称的、agent 无关的。Unity 的集成最深：编译和测试通过 Unity 官方 CLI（unity command / unity job）驱动打开着的 Editor。Godot、Unreal 和 S&box 通过 Python 桥接达到运行时对等。Claude Code 拥有 28 个 skill、自动编译 hook 和审阅门。Codex、Cursor、Continue 和任何 MCP 兼容宿主通过 MCP 和普通脚本访问相同的底层运行时。.qq/ 中的结构化状态是磁盘上的纯 JSON——任何 agent 都能跨会话读取。

方法论基于 AI 编程实践：独立开发者的文档驱动方法。

工作原理

Edit .cs/.gd/.cpp file
  → Hook 通过 qq-compile.sh 自动编译
    → 结果 + 错误上下文写入 .qq/state/
      → /qq:go 读状态，推荐下一个 skill
        → Skill 跑完，写新状态
          → 循环

四层协作：

• Hooks 在每次 Claude Code 工具调用时触发。PostToolUse 在 Edit/Write 编辑引擎源文件后通过 qq-compile.sh（多引擎分派器）编译。PreToolUse 在审阅验证期间或编译红灯之后阻止编辑，直到对应的门解除。Stop 在 skill 修改后未运行 /qq:self-review 时阻止会话结束。
• 控制器 —— /qq:go 读取 .qq/state/*.json、最近的运行记录、你的 work_mode 和当前 policy_profile，然后路由到下一个 skill。它是控制器，不是实现引擎——只在状态模糊时才回退到上下文启发式。
• 引擎桥接 —— Unity 走官方 Unity CLI（还装着 tykit 的项目才回落到 tykit）、godot_bridge.py、unreal_bridge.py、sbox_bridge.py。编译、测试、控制台、find / inspect——经过验证的执行，而非盲目文件写入。
• 运行时数据 —— .qq/runs/*.json（原始运行日志）、.qq/state/*.json（最新编译/测试状态）、.qq/state/session-decisions.json（跨 skill 决策日志）、.qq/telemetry/。纯 JSON，任何 agent 都能跨会话读取。

代码审阅有两种对称模式共享相同的验证循环：Codex 审阅（code-review.sh → codex exec，跨模型）和 Claude 审阅（claude-review.sh → claude -p，单模型）。每种都产出发现，然后独立的验证子 agent 对照实际源码逐条检查并标记过度设计——最多 5 轮直到通过。统一审阅门（scripts/hooks/review-gate.sh）在所有验证子 agent 完成前阻止编辑（三字段格式：<ts>:<completed>:<expected>）。MCP 为非 Claude 宿主提供一次性 qq_code_review 和 qq_plan_review 工具。

详见 架构总览、Hook 系统、跨模型审阅 和 并行 Worktree。

引擎

引擎	编译	测试	编辑器控制	桥接
Unity 2021.3+ ✅ verified	官方 Unity CLI（unity command recompile）/ tykit / refresh trigger	EditMode + PlayMode	官方 Unity CLI	qq_mcp.py（qq_* 工具）
Godot 4.x 🧪 preview	GDScript check via headless editor	GUT / GdUnit4	Editor addon	godot_bridge.py
Unreal 5.x 🧪 preview	UnrealBuildTool + editor commandlet	Automation tests	Editor command (Python)	unreal_bridge.py
S&box 🧪 preview	dotnet build	Runtime tests	Editor bridge	sbox_bridge.py

Unity 是已验证路径，每天通过官方 Unity CLI 驱动打开着的 Editor 实战使用（见 Unity Editor 通道）。Godot、Unreal、S&box 以实验性脚手架形式出货：适配器代码、桥接接口和 CI smoke test 都到位了，但还没有人用任何非 Unity 适配器实际开发过游戏。把它们当成贡献者的起点，而不是生产就绪的路径——参见 CONTRIBUTING.md。

安装

前置条件

• macOS 或 Windows（Windows 需要 Git for Windows 提供 bash 和核心工具）
• 引擎：Unity 2021.3+ / Godot 4.x / Unreal 5.x / S&box
• python3（必需）、jq（推荐——hook 脚本在 jq 缺失时会 fallback 到 python3）
• Claude Code（完整 skill + hook 体验）
• Codex CLI（可选——启用跨模型审阅）

安装运行时

所有 agent 共享同一套运行时安装。它自动检测引擎并将脚本、桥接和配置写入项目。

git clone https://github.com/tykisgod/quick-question.git /tmp/qq
/tmp/qq/install.sh /path/to/your-project          # 自动检测引擎
/tmp/qq/install.sh --wizard /path/to/your-project  # 交互式向导
/tmp/qq/install.sh --preset quickstart /path/to/your-project  # 一键预设
rm -rf /tmp/qq

可用预设：quickstart（最轻量）、daily（推荐）、stabilize（发版前完整检查）。细粒度控制参见 --profile、--modules 和 --without。

接入你的 agent

Agent	接入命令	你将获得
Claude Code	/plugin marketplace add tykisgod/quick-question/plugin install qq@quick-question-marketplace	全部 28 个 /qq:* slash 命令、自动编译 hook、审阅门、MCP——完整体验
Codex CLI	python3 ./scripts/qq-codex-mcp.py install --pretty	项目本地 MCP 桥接；用 qq-codex-exec.py 固定工作根目录
Cursor / Continue / 其他 MCP 宿主	在宿主配置的 mcpServers 加 qq：command: python3、args: ["./scripts/qq_mcp.py"]、cwd: /path/to/project	编译、测试、策略检查、项目状态、审查作为 qq_* MCP tool；Godot、Unreal、S&box 另有各自的编辑器桥接工具——参见 docs/dev/agent-integration.md
任何 shell	在项目根目录跑 ./scripts/qq-compile.sh / ./scripts/qq-test.sh	和 hook 走同一条编译、测试路径；Unity Editor 的其他查询用官方 Unity CLI——参见 shared/unity-cli-reference.md

非 Unity 引擎直接调用桥接脚本（如 python3 ./scripts/godot_bridge.py compile）。

快速开始

80/20 原则：qq 有 28 个命令，但绝大部分价值集中在其中 4 个。这一节是最快的 ROI 路径——掌握那 20% 真正重要的，剩下的等到你真的需要再说。

第一步 —— 设置默认 work_mode

work_mode 控制流程的严格程度。选最轻量的模式 来匹配任务，需要时再升级。

模式	适用场景	它做什么
prototype	试玩法、灰盒、fun check	只要编译绿灯。跳过正式文档和审阅。
feature ⭐	常规功能开发的默认值	计划 + 实现 + 测试 + 定向审阅。平衡型。
fix	复现并修复明确 bug	先复现，最小安全修复，回归测试。
hardening	合并前 / 发版前 / 高风险重构	测试 + 审阅 + 文档对比 + 最佳实践。严格闸门。

在 .qq/local.yaml 里设一次：

work_mode: feature

新用户最常犯的错误是默认让项目停在 hardening，然后抱怨 qq "太啰嗦"。日常待在 feature，只在 merge 前切到 hardening。

第二步 —— 学一条主循环，不是 28 个命令

90% 的任务，你只需要这 4 个命令：

/qq:go "你想做的事情"      # 根据 .qq/state 和 work_mode 决定下一步
/qq:execute                # 实现——每次 .cs 编辑自动编译
/qq:test                   # 跑测试 + 从 Editor.log 抓运行时错误
/qq:best-practice          # 快速反模式 + 性能扫描

/qq:go 是自适应入口——它读 .qq/state 和你的 work_mode，自动路由到正确的 skill。任务清晰 时直接跳到 /qq:execute；任务模糊 时让 /qq:go 路由你先走 /qq:design → /qq:plan。

让这套设置回本的关键是 auto-compile hook：每次 .cs 编辑触发编译，编译失败时 compile gate 会阻止进一步编辑，直到你修好。这条循环消灭的最大时间黑洞就是"我以为编过了，明天再确认"。

第三步 —— 三个覆盖大部分工作的模板

新功能开发

/qq:go "给船员系统加疲劳恢复机制"
/qq:execute
/qq:test
/qq:best-practice

修 bug（qq 进入 fix 模式 → 复现 → 最小修复 → 回归测试）

/qq:go "修复港口靠岸 bug，先复现"
/qq:execute
/qq:test

合并前闸门（只在你准备 push 或开 PR 时跑）

/qq:best-practice
/qq:claude-code-review        # 或 /qq:codex-code-review 跨模型审阅
/qq:doc-drift
/qq:test
/qq:commit-push

第四步 —— 第一周先不要碰这些

主循环跑顺之前，忍住别用 这些：

• /qq:bootstrap —— 等你信任主循环之后再说
• 重度文档 ceremony（每个任务都 /qq:design → /qq:plan → /qq:doc-drift）—— design/plan 是给真模糊的任务用的，不是每个任务的税
• 每次改动都跑跨模型审阅 —— /qq:codex-code-review 留给 merge 闸门或大重构。每轮 5–10 分钟，每改几行就跑会拖垮节奏。
• /qq:go --auto —— 端到端自动化是真的能跑，但先在手动模式建立"可预测感"
• 自定义 profile / pack / 模块切换 —— 默认值在第一周完全够用

第五步 —— 把 CLAUDE.md 改成真正的护栏

安装时会复制一份 CLAUDE.md 模板到你的项目。把模板里的套话替换成你项目真正在乎的 5–8 条硬规则，不要写成作文。Unity 游戏项目的示例规则：

• Runtime 逻辑禁止反射
• 未明确要求时不要改 UI / prefab 命名 / inspector 暴露字段
• Update / FixedUpdate 路径里禁止 GetComponent / FindObjectOfType
• 改完 .cs 必须验证编译绿灯才能汇报"完成"
• 优先沿用现有模式，不要发明第二套框架
• 不要为假设的未来需求增加抽象层

这是 ROI 最高的一项定制——它直接降低模型"自作聪明往错方向走"的频率。

两个警告

1. 不要把 .qq/runs/*.json 原始日志塞进 prompt。 那是运维 telemetry，不是上下文。真需要状态时跑 qq-project-state.py --pretty 拿结构化快照。
2. 不要每改一点就跑跨模型审阅。 它会让循环感觉很慢，你会因为错误的原因开始讨厌 qq。Cross-model review 留给 merge 闸门和大重构。

第一周自检

一周后，问自己 4 个问题：

1. 手动回 Unity 查编译结果的次数有没有明显下降？
2. 因为 AI "说完成了但其实没好"导致的返工有没有下降？
3. 中型功能的收尾时间有没有变短？
4. 审阅闸门 / ceremony 有没有开始让你觉得烦？

如果 1–3 改善了、4 还可以接受，就继续加码。如果 4 让你受不了，把项目降到 feature 或 prototype，只在 merge 前临时切 hardening——profile 系统本来就是为这种分层设计的。

→ 更深入的演练：快速上手 · 配置参考 · Worktrees

命令

工作流

命令	描述
/qq:go	检测工作流阶段，推荐下一步
/qq:bootstrap	从游戏愿景分解成 epics，编排完整 pipeline
/qq:design	编写游戏设计文档
/qq:plan	生成技术实现计划
/qq:execute	智能实现，自动编译验证

测试

命令	描述
/qq:add-tests	编写 EditMode、PlayMode 或回归测试
/qq:test	运行测试并检查运行时错误

代码审阅

命令	描述
/qq:codex-code-review	跨模型：Codex 审阅，Claude 验证（最多 5 轮）
/qq:codex-plan-review	跨模型计划/设计审阅
/qq:claude-code-review	Claude 单模型深度代码审阅，自动修复循环
/qq:claude-plan-review	Claude 单模型计划/设计审阅
/qq:best-practice	快速扫描反模式和性能问题
/qq:self-review	审阅最近的 skill / 配置变更
/qq:post-design-review	从实现者视角审查设计文档——检查自洽性、可实现性、代码库差距

分析

命令	描述
/qq:brief	架构图 + PR 审阅清单（对比基准分支）
/qq:timeline	提交历史按语义阶段分组
/qq:full-brief	并行运行 brief + timeline
/qq:deps	分析 .asmdef 依赖关系（Mermaid 图 + 矩阵）
/qq:doc-drift	对比设计文档与实际代码，找出不一致
/qq:doc-sync	把漂移的文档拉回与代码一致——检测、起草、人工确认后落地

工具

命令	描述
/qq:commit-push	批量提交并推送
/qq:explain	用通俗语言解释模块架构
/qq:grandma	用日常类比解释概念
/qq:tech-research	搜索开源社区寻找技术解决方案
/qq:record	录游戏运行中的效果视频和截图组，带字幕编成 mp4、抽帧自查、出验收页
/qq:design-research	搜索游戏设计参考和设计模式
/qq:changes	汇总当前会话的所有变更
/qq:doc-tidy	扫描并建议文档清理

工作模式

模式	适用场景	必须做	通常跳过
prototype	新玩法、灰盒、fun check	保持编译绿灯，可运行	正式文档，完整审阅
feature	构建可保留的系统	设计、计划、编译、定向测试	每次改动跑完整回归
fix	bug 修复、回归修复	先复现，最小安全修复	大规模重构
hardening	风险重构、发版前	测试、审阅、文档/代码一致性	原型快捷方式

在 qq.yaml 中设置共享默认值。在 .qq/local.yaml 中按 worktree 覆盖。work_mode 和 policy_profile 是独立的：前者回答"这是什么类型的任务？"，后者回答"这个项目需要多少验证？"。原型和加固阶段可以共享同一个 policy profile，也可以不。完整参考参见 配置参考。

配置

三个文件控制 qq 在你项目中的行为：

• qq.yaml —— 运行时配置：work_mode、policy_profile、trust_level、workflow（重审核 / 原型 loop）、模块选择。内置 profile：lightweight、core、feature、hardening。参见 templates/qq.yaml.example。
• CLAUDE.md —— 项目级编码规范和编译验证规则。参见 templates/CLAUDE.md.example。
• AGENTS.md —— 子 agent 工作流的架构规则和审阅标准。参见 templates/AGENTS.md.example。

Unity Editor 通道

qq 通过 Unity 官方 CLI（unity command / unity job）连到打开着的 Unity Editor，CLI 背后是 Unity 的 Pipeline 服务（包 com.unity.pipeline）。项目里有有效的 Library/Pipeline/.unity-pipeline-port、并且找得到 unity CLI（在 PATH 上，或者 QQ_UNITY_CLI 指定的位置）时：自动编译跑 unity command recompile，Unity 失焦或最小化时也能编，不会把窗口拉到前台；/qq:test 把 EditMode 作为 detach 作业提交、PlayMode 异步跑，红绿看测试汇总，不看任何 success 字段。

python3 ./scripts/qq-unity-cli.py channel --project .   # 这个项目用哪个通道：unity-cli、tykit 或 none

不要打印 Library/Pipeline/.unity-pipeline-port：里面的 token 能在 Editor 里执行任意 C#，qq 只读它的 port / pid / projectPath。找不到活着的 Editor 时，编译和测试退 2，不会另起一个 batch mode 的 Unity 去和打开着的 Editor 抢项目锁；batch mode 只在显式 --batch 时才跑。参见 shared/unity-live-state.md、shared/unity-cli-reference.md 和 Hook 系统。

tykit。 qq 不再安装 tykit（packages/com.tyk.tykit/ 里那个 Editor 内的 HTTP 服务器），也不再安装它的 Python 和 MCP 桥接。还装着 tykit 的项目照常能用：没有可用的官方 CLI 通道时，编译和测试脚本会回落到 tykit。这个包也能脱离 qq 单独使用，参见 tykit API 参考。

常见问题

支持 Windows 吗？ 支持。需要 Git for Windows（提供 bash、curl 和核心工具）。1.15.x 和 1.16.x 系列对 Windows 支持做了大量加固——LF 行结束、路径规范化、Python Store alias 检测、hook 脚本里的 jq fallback。

必须安装 Codex CLI 吗？ 不需要。Codex CLI 启用跨模型审阅（/qq:codex-code-review），但 /qq:claude-code-review 无需它即可使用。

能和 Cursor / Copilot / Codex 等 agent 一起用吗？ 可以。运行时层（引擎桥接、.qq/ 状态、脚本）是 agent 无关的——任何能跑 shell 命令或使用 MCP 的工具都能用。28 个 /qq:* slash 命令和自动编译 hook 是 Claude Code 专属的，但底层脚本是普通的 shell 和 Python。参见 docs/dev/agent-integration.md。

编译失败了会怎样？ 自动编译 hook 捕获错误输出并显示在对话中。编译恢复前，编译门会阻止对其他引擎源文件的编辑；报错的文件和改坏编译的那个文件仍可修改。agent 读取错误信息，修好这些文件（或撤回改动），然后 hook 自动重新编译。

能不装 quick-question 单独用 tykit 吗？ 可以。将 packages/com.tyk.tykit/ 中的 UPM 包添加到你的项目。参见 tykit README。

支持哪些 Unity 版本？ 官方 Unity CLI 通道需要能跑 Pipeline 服务（包 com.unity.pipeline）的 Unity Editor。没有它的项目可以继续用 tykit 作 Editor 通道，tykit 需要 Unity 2021.3+。MCP 替代方案：mcp-unity 需要 Unity 6+；Unity-MCP 无版本要求。

贡献

欢迎贡献——参见 CONTRIBUTING.md。

许可证

MIT — 参见 LICENSE。

---

Contributing

Contributions welcome — see CONTRIBUTING.md.

License

MIT — see LICENSE.