feat: add model routing and hands-on lab

2026-09-02 14:35:27 +00:00
parent ada9b3aa19
commit 9f879ed276
13 changed files with 542 additions and 9 deletions
@@ -11,7 +11,7 @@
 <body>
 <div class="reading-progress" aria-hidden="true"><span></span></div>
 <main>
-<header class="topbar"><a class="brand" href="#top"><span class="mark">A</span> field guide</a><nav class="chapter-links" aria-label="Chapter sections"><a href="#fleet">01 fleet</a><a href="#worktrees">02 worktrees</a><a href="#skills">03 skills</a><a href="#create-skill">04 create</a><a href="#field-kit">05 field kit</a></nav><div class="topbar-tools"><div class="lang-switch" aria-label="Language"><button class="active" data-lang="en" aria-pressed="true">EN</button><span>/</span><button data-lang="pt" aria-pressed="false">PT</button></div><span class="edition">AI ENGINEERING <i></i> 01 / 2026</span></div></header>
+<header class="topbar"><a class="brand" href="#top"><span class="mark">A</span> field guide</a><nav class="chapter-links" aria-label="Chapter sections"><a href="#fleet">01 fleet</a><a href="#worktrees">02 worktrees</a><a href="#models">03 models</a><a href="#skills">04 skills</a><a href="#create-skill">05 create</a><a href="#field-kit">06 field kit</a><a href="#hands-on">07 hands-on</a></nav><div class="topbar-tools"><div class="lang-switch" aria-label="Language"><button class="active" data-lang="en" aria-pressed="true">EN</button><span>/</span><button data-lang="pt" aria-pressed="false">PT</button></div><span class="edition">AI ENGINEERING <i></i> 01 / 2026</span></div></header>
 <section class="hero" id="top"><div><p class="eyebrow">A presentation for humans who ship</p><h1>AI for<br /><em>dummies.</em></h1><p class="lede">You do not need an army of models. You need a system: one mind to frame the work, several hands to execute it, and a clean boundary between every task.</p></div><aside class="hero-index"><span>FIELD NOTE / 001</span><strong>Ship the<br /><em>system.</em></strong><small>Skills · agents · worktrees · proof</small></aside></section>
 <section class="hero-stats" aria-label="Chapter summary"><div><strong>01</strong><span>strong model<br />for ambiguity</span></div><div><strong>03</strong><span>bounded workers<br />in parallel</span></div><div><strong>∞</strong><span>iterations<br />with evidence</span></div><p>Read this as a route map, not a prompt recipe.</p></section>
 <section class="thesis"><div><span>RULE ZERO</span><strong>Strong model for ambiguity.<br />Light model for bounded work.</strong></div><div class="signal" aria-hidden="true"><b>THINK</b><i></i><i></i><i></i><b>MAKE</b></div></section>
@@ -21,9 +21,11 @@
 <section class="handoff"><div class="section-label"><span>What crosses contexts</span><span>brief → diff → evidence</span></div><table><thead><tr><th>Package</th><th>Contains</th><th>Why it matters</th></tr></thead><tbody><tr><th scope="row">Brief</th><td>goal, files, boundaries</td><td>stops the worker inventing the problem</td></tr><tr><th scope="row">Worktree</th><td>branch and isolated checkout</td><td>parallel edits do not collide</td></tr><tr><th scope="row">Checks</th><td>tests, build, criteria</td><td>turns “looks good” into evidence</td></tr><tr><th scope="row">Diff</th><td>small, reviewable change</td><td>integration and discard stay cheap</td></tr></tbody></table></section>
 <section class="worktrees" id="worktrees"><div class="worktree-intro"><p class="eyebrow">Git worktrees</p><h2>One branch<br />per <em>hand.</em></h2><p>A worktree is another directory linked to the same repository. Each agent gets its own checkout and index; history remains shared.</p><p class="interaction-hint">Select a node to inspect its checkout, owner, and next action.</p></div><div class="tree-lab"><div class="tree-toolbar"><span>repository topology</span><span class="tree-live"><i></i> 4 checkouts</span></div><div class="tree-stage" role="tree" aria-label="Repository worktree topology"><svg viewBox="0 0 760 330" preserveAspectRatio="none" aria-hidden="true"><path class="tree-edge trunk" d="M380 48 V118"/><path class="tree-edge" d="M380 118 C380 170 110 150 110 224"/><path class="tree-edge" d="M380 118 V224"/><path class="tree-edge" d="M380 118 C380 170 650 150 650 224"/></svg><button class="tree-node root active" data-tree="main" role="treeitem" aria-selected="true"><span>ROOT</span><strong>main</strong><small>● clean</small></button><button class="tree-node branch ui" data-tree="ui" role="treeitem" aria-selected="false"><span>UI AGENT</span><strong>agent/ui</strong><small>3 files · working</small></button><button class="tree-node branch tests" data-tree="tests" role="treeitem" aria-selected="false"><span>TEST AGENT</span><strong>agent/tests</strong><small>8 checks · ready</small></button><button class="tree-node branch docs" data-tree="docs" role="treeitem" aria-selected="false"><span>DOCS AGENT</span><strong>agent/docs</strong><small>2 pages · review</small></button></div><article class="tree-detail" id="tree-detail" aria-live="polite"></article></div></section>
 <section class="routing"><div><p class="eyebrow">Model routing</p><h2>Do not pay for<br />reasoning where<br />you need <em>rhythm.</em></h2><p class="interaction-hint">Choose a job to see why the model profile changes.</p></div><div class="route-console"><div class="route-table"><div class="head"><span>Work</span><span>Profile</span><span>Prompt shape</span></div><button class="active" data-route="plan" aria-pressed="true"><strong>Plan</strong><b>strong / broad</b><small>What changes? What can break?</small></button><button data-route="build" aria-pressed="false"><strong>Build</strong><b>fast / focused</b><small>Implement this slice. Run these checks.</small></button><button data-route="explore" aria-pressed="false"><strong>Explore</strong><b>read-only / light</b><small>Find where this contract is used.</small></button><button data-route="review" aria-pressed="false"><strong>Review</strong><b>independent</b><small>Does the diff satisfy the brief?</small></button></div><article class="route-detail" id="route-detail" aria-live="polite"></article></div></section>
+<section class="model-gearbox" id="models"><div class="section-label"><span>Model gearbox</span><span>capability tier × thinking effort</span></div><div class="gearbox-intro"><div><p class="eyebrow">Two separate knobs</p><h2>Choose the engine.<br />Then choose the <em>gear.</em></h2></div><p>A stronger model changes the capability ceiling. Higher reasoning effort gives that model more room to work. Start with the lightest combination that passes your real checks, then move one knob at a time.</p></div><div class="gearbox"><div class="provider-tabs" role="tablist" aria-label="Model providers"><button class="active" data-model-provider="openai" role="tab" aria-selected="true">OPENAI</button><button data-model-provider="claude" role="tab" aria-selected="false">CLAUDE</button><button data-model-provider="gemini" role="tab" aria-selected="false">GEMINI</button></div><article class="provider-detail" id="provider-detail" aria-live="polite"></article><div class="effort-rail"><span>REASONING / THINKING</span><button data-effort="low" aria-pressed="false"><b>LOW</b><small>bounded + fast</small></button><button class="active" data-effort="medium" aria-pressed="true"><b>MEDIUM</b><small>default start</small></button><button data-effort="high" aria-pressed="false"><b>HIGH</b><small>complex + costly</small></button></div><article class="effort-detail" id="effort-detail" aria-live="polite"></article></div><div class="gearbox-rule"><span>ROUTING RULE</span><strong>Use strong models for ambiguity and judgment. Use lighter models for bounded execution. Raise effort only when evaluation shows a gain.</strong></div></section>
 <section class="skills" id="skills"><div><p class="eyebrow">Skills</p><h2>Write the right way<br /><em>once.</em></h2><p>A skill is a reusable procedure. It can carry instructions, references, scripts, and assets. It is not magical memory, and it does not replace acceptance criteria.</p><div class="skill-principles"><span>01 / trigger clearly</span><span>02 / load detail on demand</span><span>03 / return evidence</span></div></div><div class="skill-explorer"><div class="skill-package" role="tree" aria-label="Skill package files"><span>SKILL PACKAGE</span><button class="active" data-skill-file="skill" role="treeitem" aria-selected="true"><code>SKILL.md</code><small>procedure and limits</small></button><button data-skill-file="references" role="treeitem" aria-selected="false"><code>references/</code><small>facts to consult</small></button><button data-skill-file="scripts" role="treeitem" aria-selected="false"><code>scripts/</code><small>repeatable checks</small></button><button data-skill-file="assets" role="treeitem" aria-selected="false"><code>assets/</code><small>templates and examples</small></button></div><article class="skill-detail" id="skill-detail" aria-live="polite"></article></div><pre><code>name: review-ui · check focus, mobile, reduced motion · run verification · return evidence</code></pre></section>
 <section class="skill-builder" id="create-skill"><div class="section-label"><span>Create a skill</span><span>repeatable pain → reusable judgment</span></div><div class="builder-intro"><div><p class="eyebrow">The skill forge</p><h2>Teach the decision.<br />Keep the context <em>light.</em></h2></div><p>Do not package everything you know. Capture the non-obvious choices that repeatedly improve an outcome, then prove the skill changes behavior.</p></div><div class="builder-workbench"><nav class="builder-steps" role="tablist" aria-label="Skill creation workflow"><button class="active" data-skill-step="observe" role="tab" aria-selected="true"><b>01</b><span>Observe</span><small>find repeated friction</small></button><button data-skill-step="trigger" role="tab" aria-selected="false"><b>02</b><span>Define trigger</span><small>route precisely</small></button><button data-skill-step="scaffold" role="tab" aria-selected="false"><b>03</b><span>Choose anatomy</span><small>only needed files</small></button><button data-skill-step="write" role="tab" aria-selected="false"><b>04</b><span>Write guidance</span><small>decisions, not trivia</small></button><button data-skill-step="validate" role="tab" aria-selected="false"><b>05</b><span>Validate</span><small>test real behavior</small></button></nav><article class="builder-detail" id="builder-detail" aria-live="polite"></article><aside class="builder-artifact"><div class="artifact-head"><span>OUTPUT / SKILL PACKAGE</span><i></i></div><pre aria-label="Example skill structure"><code>review-ui/<br />├── SKILL.md<br />├── agents/<br />│   └── openai.yaml<br />├── references/<br />│   └── accessibility.md<br />└── scripts/<br />    └── verify.mjs</code></pre><div class="artifact-command"><span>VALIDATE</span><code>quick_validate.py ./review-ui</code></div></aside></div><div class="builder-loop"><span>AFTER REAL USE</span><div><b>observe failure</b><i>→</i><b>sharpen one rule</b><i>→</i><b>retest behavior</b><i>→</i><b>keep it narrow</b></div></div></section>
-<section class="skill-catalog" id="field-kit"><div class="section-label"><span>Common skills</span><span>choose behavior before model</span></div><div class="catalog-intro"><div><p class="eyebrow">The field kit</p><h2>Different jobs.<br />Different <em>instincts.</em></h2></div><p>A skill changes how an agent approaches work. Some shape communication. Others enforce research, debugging, review, or completion discipline. Select one to inspect its operating rule.</p></div><div class="skill-deck"><div class="skill-index" role="tablist" aria-label="Common agent skills"><button class="active" data-common-skill="ponytail" role="tab" aria-selected="true"><span>SIMPLIFY</span><strong>ponytail-lite</strong><small>minimum code that holds</small></button><button data-common-skill="caveman" role="tab" aria-selected="false"><span>COMMUNICATE</span><strong>caveman</strong><small>signal without filler</small></button><button data-common-skill="unlazy" role="tab" aria-selected="false"><span>COMPLETE</span><strong>unlazy</strong><small>gates and evidence</small></button><button data-common-skill="research" role="tab" aria-selected="false"><span>INVESTIGATE</span><strong>research</strong><small>primary sources first</small></button><button data-common-skill="debug" role="tab" aria-selected="false"><span>DIAGNOSE</span><strong>diagnosing-bugs</strong><small>tight feedback loop</small></button><button data-common-skill="review" role="tab" aria-selected="false"><span>REVIEW</span><strong>code-review</strong><small>standards × spec</small></button><button data-common-skill="tokens" role="tab" aria-selected="false"><span>ECONOMIZE</span><strong>token-saver</strong><small>compress noisy output</small></button></div><article class="common-skill-detail" id="common-skill-detail" aria-live="polite"></article></div><div class="skill-loadout"><span>ONE PRACTICAL LOADOUT</span><div><b>PLAN</b> unlazy <i>→</i> <b>BUILD</b> ponytail-lite <i>→</i> <b>DEBUG</b> diagnosing-bugs <i>→</i> <b>REPORT</b> caveman</div></div></section>
+<section class="skill-catalog" id="field-kit"><div class="section-label"><span>Common skills</span><span>choose behavior before model</span></div><div class="catalog-intro"><div><p class="eyebrow">The field kit</p><h2>Different jobs.<br />Different <em>instincts.</em></h2></div><p>A skill changes how an agent approaches work. Some shape communication. Others enforce research, debugging, review, or completion discipline. Select one to inspect its operating rule and verified source.</p></div><div class="skill-deck"><div class="skill-index" role="tablist" aria-label="Common agent skills"><button class="active" data-common-skill="ponytail" role="tab" aria-selected="true"><span>SIMPLIFY</span><strong>ponytail-lite</strong><small>minimum code that holds</small></button><button data-common-skill="caveman" role="tab" aria-selected="false"><span>COMMUNICATE</span><strong>caveman</strong><small>signal without filler</small></button><button data-common-skill="unlazy" role="tab" aria-selected="false"><span>COMPLETE</span><strong>unlazy</strong><small>gates and evidence</small></button><button data-common-skill="research" role="tab" aria-selected="false"><span>INVESTIGATE</span><strong>research</strong><small>primary sources first</small></button><button data-common-skill="debug" role="tab" aria-selected="false"><span>DIAGNOSE</span><strong>diagnosing-bugs</strong><small>tight feedback loop</small></button><button data-common-skill="review" role="tab" aria-selected="false"><span>REVIEW</span><strong>code-review</strong><small>standards × spec</small></button><button data-common-skill="tokens" role="tab" aria-selected="false"><span>ECONOMIZE</span><strong>token-saver</strong><small>compress noisy output</small></button></div><article class="common-skill-detail" id="common-skill-detail" aria-live="polite"></article></div><div class="skill-loadout"><span>ONE PRACTICAL LOADOUT</span><div><b>PLAN</b> unlazy <i>→</i> <b>BUILD</b> ponytail-lite <i>→</i> <b>DEBUG</b> diagnosing-bugs <i>→</i> <b>REPORT</b> caveman</div></div><article class="install-skills"><header><div><span>INSTALL PACK</span><strong>Ask your coding agent to verify, install, and validate the skills.</strong></div><button data-copy-target="prompt-install-skills"><span>COPY</span><i aria-hidden="true">↗</i></button></header><pre><code id="prompt-install-skills"></code></pre><footer>Review every source before installation. Existing local skills must be preserved.</footer></article></section>
+<section class="hands-on" id="hands-on"><div class="section-label"><span>Hands-on</span><span>10 minutes / one missing feature</span></div><div class="hands-intro"><div><p class="eyebrow">Tiny Tasks lab</p><h2>Same task.<br />Better <em>operating system.</em></h2></div><div><p>Start with a deliberately incomplete static task board. Run one prompt as written, reset, then run the skill-enabled version. Compare diff size, verification evidence, and unnecessary complexity.</p><a href="hands-on/starter/" class="starter-link">Open the starter project →</a></div></div><div class="exercise-brief"><span>THE MISSING FEATURE</span><strong>Add All / Open / Done filters that survive reload and browser navigation.</strong><div><b>STACK</b> HTML · CSS · JavaScript <b>DEPENDENCIES</b> none <b>FILES</b> 3</div></div><div class="prompt-compare"><article class="prompt-card"><header><div><span>RUN A</span><strong>Good prompt</strong></div><button data-copy-target="prompt-basic"><span>COPY</span><i aria-hidden="true">↗</i></button></header><pre><code id="prompt-basic"></code></pre><footer>Clear context · constraints · acceptance · evidence</footer></article><article class="prompt-card enhanced"><header><div><span>RUN B</span><strong>Good prompt + skills</strong></div><button data-copy-target="prompt-skills"><span>COPY</span><i aria-hidden="true">↗</i></button></header><pre><code id="prompt-skills"></code></pre><footer>Same contract · explicit working methods · stronger proof</footer></article></div><div class="comparison-strip"><span>COMPARE THE RUNS</span><div><b>01</b> Files changed</div><div><b>02</b> New dependencies</div><div><b>03</b> Checks actually run</div><div><b>04</b> Evidence returned</div></div><p class="copy-status" id="copy-status" role="status" aria-live="polite"></p></section>
 <aside class="rule"><span>THE HUMAN JOB</span><strong>The agent may be autonomous in execution. Intent, boundaries, and evidence remain yours.</strong></aside><aside class="callout"><span>START HERE</span><strong>Begin with one agent and one skill. Add parallelism only when the tasks are truly independent.</strong></aside>
 <section class="sources"><div class="section-label"><span>Keep learning</span><span>12 new readings + primary docs</span></div><p>Go deeper with official documentation, production case studies, Medium, and practitioner workflows. <a href="docs/references/README.md">Primary references →</a> <a href="docs/references/additional-reading.md">12-part reading path →</a></p></section>
 </main><script src="app.js" defer></script>