quick-question — плагин для Claude Code: игровая разработка с Unity
Плагин quick-question для Claude Code, который компилирует C# на каждой правке, запускает тесты Unity и проверяет код субагентами с верификацией каждой находки перед исправлением. Работает с Unity 2021.3+ на macOS и Windows.
MIT ★ 13 обновлён 2026-10-17
/plugin marketplace add anthropics/claude-plugins-community
/plugin install quick-question@claude-communityЧто делает quick-question
Подключается к редактору Unity через официальный CLI (unity command, unity job) и автоматически компилирует после каждой правки файла. Запускает EditMode и PlayMode тесты, читает консоль, инспектирует GameObject. Результаты компиляции, тестов и ревью пишутся в .qq/state/*.json — любой агент может прочитать состояние проекта между сессиями.
Ревью кода делают субагенты: сначала находят проблемы, потом каждая находка проходит независимую верификацию против исходников, чтобы отсечь ложные срабатывания и избыточные правки. Хуки блокируют правку файлов, пока верификация не завершится, и запрещают закрывать сессию, если скиллы изменены без /qq:self-review. Без FFmpeg в PATH видеозапись тестов не работает.
28 слэш-команд покрывают цикл от правки до шипа. Четыре режима работы (prototype, feature, fix, hardening) управляют тем, что запускается автоматически: прототип держит зелёный билд и остаётся играбельным, hardening форсирует тесты и проверку согласованности документов с кодом.
Какие задачи решает
- скомпилировать C# после каждой правки автоматически
- запустить тесты Unity из Claude Code и получить результат в контекст
- проверить код субагентами и отсечь ложные находки до правки
- прочитать состояние проекта из
.qq/state/*.jsonв новой сессии - заблокировать правку файлов, пока ревью не завершено
Примеры запросов агенту
- Скомпилируй проект и запусти EditMode тесты
- Открой консоль Unity и покажи последние ошибки
- Запусти
/qq:goи порекомендуй следующий шаг по состоянию.qq/state/
Как установить quick-question
Через маркетплейс плагинов
/plugin marketplace add anthropics/claude-plugins-community/plugin install quick-question@claude-communityПо шагам, с командами для каждой платформы: Плагины Claude Code: маркетплейсы, установка и как собрать свой
Вопросы о quick-question
Как установить quick-question в Claude Code?
Сначала выполни /plugin marketplace add anthropics/claude-plugins-community, затем /plugin install quick-question@claude-community.
Что делает quick-question?
Компилирует C# после каждой правки, запускает тесты Unity через официальный CLI, проверяет код субагентами с верификацией находок и пишет состояние проекта в .qq/state/*.json для чтения между сессиями.
С какими версиями Unity работает quick-question?
С Unity 2021.3 и новее на macOS и Windows. Другие движки (Godot, Unreal, S&box) пока экспериментальны.
Исходный текст
SKILL.md · MIT
<p align="center">
<img src="logo.png" alt="quick-question" width="200">
</p>
<h1 align="center">quick-question</h1>
<p align="center">
<strong>The control plane for game-dev agents.</strong><br>
Close the loop — compile, test, review, and ship — across Unity, Godot, Unreal, and S&box.<br>
<a href="https://docs.anthropic.com/en/docs/claude-code">Claude Code</a>-first.
Open to any agent via HTTP and MCP.
</p>
<p align="center">
<a href="https://github.com/tykisgod/quick-question/actions/workflows/validate.yml"><img src="https://github.com/tykisgod/quick-question/actions/workflows/validate.yml/badge.svg" alt="CI"></a>
<img src="https://img.shields.io/badge/version-v1.24.0-blue" alt="Version">
<a href="https://github.com/tykisgod/quick-question/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
<img src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows-blue" alt="Platform">
</p>
<table align="center" cellspacing="0" cellpadding="16" border="0">
<tr>
<td align="center" border="0">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/images/unity-light.svg">
<img src="docs/images/unity-dark.svg" width="56" alt="Unity">
</picture>
<br>
<a href="https://unity.com">Unity</a>
</td>
<td align="center" border="0">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/images/godot-light.svg">
<img src="docs/images/godot-dark.svg" width="56" alt="Godot">
</picture>
<br>
<a href="https://godotengine.org">Godot</a>
</td>
<td align="center" border="0">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/images/unreal-light.svg">
<img src="docs/images/unreal-dark.svg" width="56" alt="Unreal">
</picture>
<br>
<a href="https://www.unrealengine.com">Unreal</a>
</td>
<td align="center" border="0">
<img src="docs/images/sbox.svg" width="56" alt="S&box">
<br>
<a href="https://github.com/Facepunch/sbox-public">S&box</a>
</td>
</tr>
</table>
<p align="center">
English |
<a href="#中文">中文</a> |
<a href="docs/ja/README.md">日本語</a> |
<a href="docs/ko/README.md">한국어</a>
</p>
---
> **✅ 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](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](https://docs.anthropic.com/en/docs/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*](https://tyksworks.com/posts/ai-coding-workflow-en/).
## 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](docs/dev/architecture/overview.md), [Hook System](docs/en/hooks.md), [Cross-Model Review](docs/en/cross-model-review.md), and [Worktrees](docs/en/worktrees.md) 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](#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](CONTRIBUTING.md).
## Install
### Requirements
- macOS or Windows (Windows needs [Git for Windows](https://gitforwindows.org/) 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](https://docs.anthropic.com/en/docs/claude-code) for the full skill + hook experience
- [Codex CLI](https://github.com/openai/codex) (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.
```bash
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`<br>`/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`](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`](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`:
```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:
```bash
/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**
```bash
/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)
```bash
/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)
```bash
/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](docs/en/getting-started.md) · [Configuration](docs/en/configuration.md) · [Worktrees](docs/en/worktrees.md)
## 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](docs/en/configuration.md) 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`](templates/qq.yaml.example).
- **`CLAUDE.md`** — coding standards and compile verification rules scoped to your project. See [`templates/CLAUDE.md.example`](templates/CLAUDE.md.example).
- **`AGENTS.md`** — architecture rules and review criteria for subagent workflows. See [`templates/AGENTS.md.example`](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.
```bash
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-live-state.md), [`shared/unity-cli-reference.md`](shared/unity-cli-reference.md), and [Hook System](docs/en/hooks.md).
**tykit.** qq no longer installs tykit (the in-Editor HTTP server in [`packages/com.tyk.tykit/`](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`](docs/en/tykit-api.md).
## FAQ
**Does this work on Windows?**
Yes. Requires [Git for Windows](https://gitforwindows.org/) 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`](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/`](packages/com.tyk.tykit/). See the [tykit README](packages/com.tyk.tykit/README.md).
**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](https://github.com/nicoboss/mcp-unity) requires Unity 6+; [Unity-MCP](https://github.com/mpiechot/Unity-MCP) has no version requirement.
---
<!--
╔════════════════════════════════════════════════════════════════════════╗
║ ⚠️ DO NOT EDIT THE CHINESE SECTION BELOW DIRECTLY ║
║ ║
║ The Chinese half of this README is AUTO-GENERATED from ║
║ docs/zh-CN/README.md ║
║ by scripts/qq-sync-readme-zh.py. ║
║ ║
║ To update Chinese content: ║
║ 1. Edit docs/zh-CN/README.md ║
║ 2. Run python scripts/qq-sync-readme-zh.py --write ║
║ 3. Commit BOTH docs/zh-CN/README.md AND README.md ║
║ ║
║ CI enforces sync via test.sh section 4 and qq-release.sh pre-flight. ║
║ Direct edits below this comment will be overwritten on next sync. ║
╚════════════════════════════════════════════════════════════════════════╝
-->
<h2 align="center">中文</h2>
> **✅ 已验证路径**:**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](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](https://docs.anthropic.com/en/docs/claude-code) 拥有 28 个 skill、自动编译 hook 和审阅门。Codex、Cursor、Continue 和任何 MCP 兼容宿主通过 MCP 和普通脚本访问相同的底层运行时。`.qq/` 中的结构化状态是磁盘上的纯 JSON——任何 agent 都能跨会话读取。
方法论基于 [*AI 编程实践:独立开发者的文档驱动方法*](https://tyksworks.com/posts/ai-coding-workflow-zh/)。
## 工作原理
```
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` 工具。
详见 [架构总览](docs/dev/architecture/overview.md)、[Hook 系统](docs/zh-CN/hooks.md)、[跨模型审阅](docs/zh-CN/cross-model-review.md) 和 [并行 Worktree](docs/zh-CN/worktrees.md)。
## 引擎
| 引擎 | 编译 | 测试 | 编辑器控制 | 桥接 |
|------|------|------|-----------|------|
| **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 通道](#unity-editor-通道))。Godot、Unreal、S&box 以**实验性脚手架**形式出货:适配器代码、桥接接口和 CI smoke test 都到位了,但还没有人用任何非 Unity 适配器实际开发过游戏。把它们当成贡献者的起点,而不是生产就绪的路径——参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 安装
### 前置条件
- macOS 或 Windows(Windows 需要 [Git for Windows](https://gitforwindows.org/) 提供 bash 和核心工具)
- 引擎:Unity 2021.3+ / Godot 4.x / Unreal 5.x / S&box
- `python3`(必需)、`jq`(推荐——hook 脚本在 jq 缺失时会 fallback 到 python3)
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)(完整 skill + hook 体验)
- [Codex CLI](https://github.com/openai/codex)(可选——启用跨模型审阅)
### 安装运行时
所有 agent 共享同一套运行时安装。它自动检测引擎并将脚本、桥接和配置写入项目。
```bash
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`<br>`/plugin install qq@quick-question-marketplace` | 全部 28 个 `/qq:*` slash 命令、自动编译 hook、审阅门、MCP——完整体验 |
| **Codex CLI** |...
© tykisgod · MIT · tykisgod/quick-question