Best Practices

## 1. Semantics in Spec, style in Adapter Never put Markdown headings, XML tags, or "let's think step by step" in your Spec. Those are "how to say it" — the adapter's job. The Spec only says "what to do". ## 2. Reasoning models ≠ normal models For o1 / R1 / QwQ, the shorter the prompt the better — just state the problem, the constraints, and the output format. The adapter auto-strips CoT prompts; you only need to get the Spec right. ## 3. Layered few-shot The examples[].reasoning field is rendered only for non-reasoning models; reasoning models auto-filter it. One Spec works great for both classes of model. ## 4. Put long docs into knowledge Kimi / Gemini inline knowledge directly. The Claude adapter emits a suggested SKILL.md for progressive disclosure. Do NOT chunk your knowledge manually — let each adapter decide. ## 5. Canonical tool schema Spec only needs name / description / parameters. The adapter converts to Anthropic tool_use / OpenAI function / Google function_declarations as needed. ## 6. Build a cross-model eval loop Run the same Spec across all models as regression tests. Pick per-task winners based on success rate + output stability + token cost — don't just trust vendor claims. | Scenario | Recommended first choice | | --- | --- | | Hard reasoning / math / competitive code | o3 · DeepSeek R1 · QwQ | | Agents with tools and long workflows | Claude Sonnet · GPT-5 | | Long docs / whole codebase understanding | Gemini 2.5 · Kimi | | Chinese content generation / local context | Qwen · GLM-4 · ERNIE · Doubao | | Cost-sensitive / high concurrency | Doubao · GPT-4o-mini · Qwen-Turbo | > **WARNING**: The model ecosystem shifts every 3–6 months. Treat adapters as infrastructure: when a new model arrives you only add one adapter file; your business code stays untouched.