Content
# Tool List
AI Design Review Framework — Multi-model adversarial design review MCP tool.
## Architecture
Fully plugin-based (all project-specific logic into adapter, core project-agnostic):
| Swappable Layer | Protocol | Default Implementation |
|---|---|---|
| `ModelBackend` (invocation layer implementation) | `async complete(...)` | `LiteLLMBackend` |
| `KnowledgeProvider` | `retrieve/list_cases/add_case` | `YamlKnowledgeProvider` |
| `ProjectAdapter` | `read_context/version/convention + reviewers/knowledge` | `UnityAdapter` / `GenericAdapter` |
| `ReportRenderer` | `render(ReviewReport)` | `MarkdownRenderer` / `JSONRenderer` |
| `Stage` (Pipeline step) | `process(ctx)->ctx` | retrieve/context/prompt/review/parse/normalize/consensus/score |
## Review Pipeline
```
ReviewDocument → RetrieveStage → ContextStage → PromptStage → ReviewStage(fan-out)
→ ParseStage → NormalizeStage(canonical) → ConsensusStage → ScoreStage → ReviewReport
```
## Knowledge Base (Important: Framework only provides generic seeds; your project's gotchas need to be added manually)
**The tool's review quality = knowledge base thickness.** The framework comes with **generic** seed cases (Unity ECS/Burst/FlowField/NetCode API-level gotchas, see `design_review/adapters/unity/knowledge/`, about a dozen cases). Your project's **own** gotchas (architecture decisions, historical bugs, conventions) won't be automatically included - you need to accumulate them, which is the tool's moat for your project, and what others can't take away even if they clone your project.
### Location
`<project_root>/.design-review/knowledge/*.yaml` (project-local). Framework knowledge base + local knowledge base are automatically merged (local cases with the same ID override framework cases). It's recommended to put project-specific/sensitive content locally and gitignore it.
### Format
```yaml
- id: MYSYSTEM-001 # Unique ID, finding references it for cross-model consensus anchoring
title: "One-sentence gotcha"
version: {entities: ">=1.4,<2.0"} # Version constraint (empty= generic); retrieve filters by project version
triggers: [keyword1, keyword2] # retrieve hits based on these words (case-insensitive)
category: ecs_perf # Organizational category; filled in finding.dimension when case_ref is hit
bad_pattern: "Anti-pattern description (will be shown in prompt to models)"
recommended_pattern: "Positive solution"
source: "MEMORY.md#xxx" # For tracking, not included in prompt
```
### Accumulation
- Transcribe from `MEMORY.md` / postmortem / bug tracker / recurring code review comments
- Each case focuses on **one specific, reproducible** gotcha (bad_pattern + recommended_pattern should be actionable, not write vague principles)
- `triggers` should contain **words that appear in the scheme text** (API names, error codes, component names, USS properties), so retrieve can hit them - this is key to recall
- Generic gotchas (any project in the same stack can encounter) can be contributed back to the framework; project-specific ones should be placed locally
## Installation
```bash
cd Tools/design-review-mcp
uv sync
```
## Configuration
API keys are passed through environment variables (litellm convention):
| Model | env | model string |
|---|---|---|
| OpenAI GPT-5 | `OPENAI_API_KEY` | `gpt-5` |
| Anthropic Claude | `ANTHROPIC_API_KEY` | `claude-opus-4-8` / `claude-sonnet-4-6` |
| Volcengine | `ARK_API_KEY` | `volcengine/<ARK_ENDPOINT_ID>` |
| DeepSeek | `DEEPSEEK_API_KEY` | `deepseek/deepseek-chat` |
| Zai GLM | `ZAI_API_KEY` | `zai/glm-4.7` |
## Register to Claude Code
Add the following to `~/.claude.json` in the corresponding project `mcpServers`:
```jsonc
"design-review": {
"type": "stdio",
"command": "uv",
"args": ["run", "--directory", "<project>/Tools/design-review-mcp", "design-review-mcp"],
"env": {
"UNITY_PROJECT_ROOT": "<project>",
"OPENAI_API_KEY": "...",
"ANTHROPIC_API_KEY": "...",
"ARK_API_KEY": "..."
}
}
```
## CLI (v1.1)
`design-review` command doesn't rely on MCP/Claude Code, can be run directly in terminal/script/CI:
```bash
design-review plan path/to/plan.md --output markdown # Review plan (file)
cat plan.md | design-review plan - # stdin
design-review plan --text "# Plan..." --dimensions planner # Pass text directly
design-review code src/a.py src/b.py --output sarif --output-file out.sarif # Review code → SARIF
design-review doc rfc.md --type rfc # Review document (markdown/adr/rfc/config)
```
## SARIF + CI Integration
`--output sarif` generates SARIF 2.1.0 (consensus/majority → results, severity→error/warning/note, with calibrated_confidence/flagged_by/case_ref), can be integrated with GitHub Code Scanning / IDE. Use design-review to review code in CI:
```yaml
# .github/workflows/design-review.yml
on: [pull_request]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v3
- run: uvx --from git+https://github.com/fanghaoling/design-review-mcp design-review code src/ --output sarif --output-file dr.sarif
env: {OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}, ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}}
- uses: github/codeql-action/upload-sarif@v3
with: {sarif_file: dr.sarif}
```
## Cost and Thinking Intensity Control (v1.5)
Two opt-in parameters, disabled by default (backward compatible, old calls remain unchanged):
- **`max_cost_usd`** (single review total cost cap in USD, default None= no cap): pre-flight estimates each job cost, greedily retains models until estimated budget exceeded, and reports `budget.exhausted` if exceeded.
- **`effort`** (thinking intensity low/medium/high/xhigh/max, default None= model defaults): only affects Claude (`output_config`+thinking adaptive) / OpenAI o-series (`reasoning_effort`), others are discarded.
## Relay Station / Custom Endpoint (v1.6)
Allow panels to reference "relay stations" (Zai Anthropic compatible endpoints, New API, one-api, etc.) that provide models. Declare endpoints in `design_review_config.json` and reference them in panel items:
```jsonc
{
"endpoints": {
"zhipu": {
"provider": "anthropic", // Compatible gateway protocol: openai | anthropic
"base_url": "https://open.bigmodel.cn/api/anthropic",
"api_key_env": "ZHIPU_KEY", // Prioritize: read key from this environment variable
// "api_key": "plaintext", // fallback (⚠️ don't let config go into git)
"headers": {}, // Optional: extra headers (only Bearer-based stations / OpenRouter)
"timeout": 120 // Optional: override global timeout (slow relay stations)
}
},
"panel": [
"gpt-4o", // str = official (litellm native provider, uses env)
"zai/glm-5.2", // litellm native provider, uses env
{"endpoint": "zhipu", "model": "glm-5.2", "label": "Zai-Anthropic Relay"}
]
}
```
## Privacy Mode (v1.7)
By default, adversarial review fans out the entire plan/code to all models in the panel. If the panel contains multiple relay stations/vendors, code and technical details may be leaked to all third-party models. **Privacy mode** allows a trusted intermediate AI to see the full text, while adversarial models only see a sanitized summary, and the trusted AI supplements evidence and assessment.
## Development
```bash
uv run pytest tests/ # Test (mock ModelBackend, no network calls)
uv run ruff check . # Lint
```
Push/PR automatically triggers GitHub Actions (`.github/workflows/ci.yml`): Python 3.10/3.11/3.12 matrix runs ruff + pytest.
## License
Apache-2.0
