diff --git a/src/pages/full-guide.astro b/src/pages/full-guide.astro new file mode 100644 index 0000000..5a1aa7e --- /dev/null +++ b/src/pages/full-guide.astro @@ -0,0 +1,597 @@ +--- +// /full-guide/ — assembled from typed guide collections and the task 10 blocks. +// This route deliberately never imports the legacy full-guide HTML: task 20 removes +// that tree, and both locales must be present in the server-rendered document. +import { getCollection } from 'astro:content'; +import BaseLayout from '../layouts/BaseLayout.astro'; +import FleetDiagram from '../components/blocks/FleetDiagram.astro'; +import HandoffTable from '../components/blocks/HandoffTable.astro'; +import PhasePanel from '../components/blocks/PhasePanel.astro'; +import RouteTable from '../components/blocks/RouteTable.astro'; +import SkillPackage from '../components/blocks/SkillPackage.astro'; +import WorktreeMap from '../components/blocks/WorktreeMap.astro'; +import CopyPrompt from '../components/islands/CopyPrompt.astro'; +import GuideSelector from '../components/islands/GuideSelector.astro'; +import LanguageToggle from '../components/islands/LanguageToggle.astro'; +import ReadingProgress from '../components/islands/ReadingProgress.astro'; +import '../../styles.css'; +import '../../responsive.css'; +import '../../full-guide/audit.css'; + +type Entry = { data: T }; +const toRecord = (entries: Entry[]) => + Object.fromEntries(entries.map(({ data }) => [data.id, data])); +const [ + phaseEntries, + workerEntries, + treeEntries, + routeEntries, + providerEntries, + effortEntries, + skillFileEntries, + workflowEntries, + commonSkillEntries, + promptEntries, + installEntries, +] = await Promise.all([ + getCollection('phases'), + getCollection('workers'), + getCollection('trees'), + getCollection('routes'), + getCollection('providers'), + getCollection('efforts'), + getCollection('skillFiles'), + getCollection('skillWorkflow'), + getCollection('commonSkills'), + getCollection('handsOnPrompts'), + getCollection('skillInstallPrompts'), +]); +const phases = toRecord(phaseEntries); +const workers = toRecord(workerEntries); +const trees = toRecord(treeEntries); +const routes = toRecord(routeEntries); +const providers = toRecord(providerEntries); +const efforts = toRecord(effortEntries); +const skillFiles = toRecord(skillFileEntries); +const skillWorkflow = toRecord(workflowEntries); +const commonSkills = toRecord(commonSkillEntries); +const handsOn = promptEntries.find(({ data }) => data.id === 'tiny-tasks')?.data; +const install = installEntries.find(({ data }) => data.id === 'install')?.data; +if (!handsOn || !install) throw new Error('full-guide content collections are incomplete'); + +// Selector chrome is page-specific, so it remains an inline bilingual constant. +const labels = { + context: { en: 'context: isolated', pt: 'contexto: isolado' }, + owner: { en: 'OWNER', pt: 'RESPONSÁVEL' }, + reasoningLoad: { en: 'REASONING LOAD', pt: 'CARGA DE RACIOCÍNIO' }, + officialSource: { en: 'OFFICIAL SOURCE ↗', pt: 'FONTE OFICIAL ↗' }, + skillFileHint: { + en: 'select another file to explore', + pt: 'clique em outro arquivo para explorar', + }, + workflow: { + question: { en: 'QUESTION', pt: 'PERGUNTA' }, + action: { en: 'ACTION', pt: 'AÇÃO' }, + artifact: { en: 'ARTIFACT', pt: 'ARTEFATO' }, + proof: { en: 'PROOF', pt: 'PROVA' }, + }, + commonSkill: { + whenToUse: { en: 'WHEN TO USE', pt: 'QUANDO USAR' }, + example: { en: 'EXAMPLE', pt: 'EXEMPLO' }, + watchOut: { en: 'WATCH OUT', pt: 'CUIDADO' }, + source: { en: 'GITHUB SOURCE ↗', pt: 'FONTE NO GITHUB ↗' }, + }, +}; +const selectorData = { + phases, + workers, + trees, + routes, + providers, + efforts, + skillFiles, + skillWorkflow, + commonSkills, + labels, +}; +const workerCards = [ + { id: 'ui', label: 'UI', strong: 'Component and visual states', code: 'agent/ui' }, + { id: 'tests', label: 'TEST', strong: 'Acceptance cases', code: 'agent/tests' }, + { id: 'docs', label: 'DOCS', strong: 'Guide and examples', code: 'agent/docs' }, +]; +const treeBranches = [ + { id: 'ui', label: 'UI AGENT', strong: 'agent/ui', small: '3 files · working', tone: 'ui' }, + { + id: 'tests', + label: 'TEST AGENT', + strong: 'agent/tests', + small: '8 checks · ready', + tone: 'tests', + }, + { + id: 'docs', + label: 'DOCS AGENT', + strong: 'agent/docs', + small: '2 pages · review', + tone: 'docs', + }, +]; +const base = import.meta.env.BASE_URL; +--- + + + +
+
+ A field guide + +
+ review submissions ↗AI ENGINEERING 01 / 2026 +
+
+ +
+
+

A presentation for humans who ship

+ AI for
dummies. +

+ 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. +

+
+
+ + +
+
01strong model
for ambiguity
+ 03bounded workers
in parallel +
∞iterations
with evidence

+ Read this as a route map, not a prompt recipe. +

+
+ + +
+
+ RULE ZEROStrong model for ambiguity.
Light model for bounded work. +
+
+ + +
+
+ A small fleetcoordination before parallelism +
needs to happen.', + code: 'Opus / reasoning', + }} + workers={workerCards} + />
+ {workers.ui.en[0]}{workers.ui.en[1]}{workers.ui.en[2]} +

+ The orchestrator preserves intent, writes small contracts, and gathers results that can be + verified. It does not need to type every line. +

+
+
+
+ Why the boundary mattersone vague task / three predictable failures +
+
+ 01Context soup

+ Every worker reads everything. Nobody knows which facts are load-bearing. +

+
+ 02Branch collision

+ Two agents touch the same checkout. The fastest path becomes conflict resolution. +

+
+ 03Confident drift

+ The diff is polished, but no one checks whether it solved the original problem. +

+
+
+
+ +
+
+

The subagent loop

+ Click a phase.
See the handoff. +

+ Delegation means moving one bounded task into a smaller context—not giving away + responsibility. +

+
+
+
+
+ What crosses contextsbrief → diff → evidence +
+
+ +
+
+

Git worktrees

One branch
per hand.

+ A worktree is another directory linked to the same repository. Each agent gets its own + checkout and index; history remains shared. +

+ Select a node to inspect its checkout, owner, and next action. +

+
+
+ repository topology 4 checkouts +
+
{labels.owner.en}{trees.main.owner.en}
+ CHECKOUT{trees.main.path} +

{trees.main.note.en}

{trees.main.command} +
+
+
+ +
+
+

Model routing

+ Do not pay for
reasoning where
you need rhythm. +

Choose a job to see why the model profile changes.

+
+
+
+ {labels.reasoningLoad.en} · {routes.plan.score}{routes.plan.label.en}

{routes.plan.why.en}

+
+
+
+
+ +
+
+ Model gearboxcapability tier × thinking effort +
+
+ +
+ +
+ {efforts.medium.en[0]}

{efforts.medium.en[1]}

{providers.openai.config} +
+
+
+ +
+
+

Skills

Write the right way
once.

+ 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. +

+
+
+ {skillFiles.skill.icon}
+ {skillFiles.skill.title}

{skillFiles.skill.en}

{labels.skillFileHint.en} +
+
+
+
+ +
+
+ Create a skillrepeatable pain → reusable judgment +
+
+
+ {skillWorkflow.observe.number}{labels.workflow.question.en} +

{skillWorkflow.observe.title.en}

+ {skillWorkflow.observe.question.en} +
+ {labels.workflow.action.en}

{skillWorkflow.observe.action.en}

+
+
+ {labels.workflow.artifact.en}{skillWorkflow.observe.output.en} +
+ {labels.workflow.proof.en}{skillWorkflow.observe.proof.en} +
+
+
+
+
+ +
+
+ Common skillschoose behavior before model +
+
+ { + Object.values(commonSkills).map((skill) => ( + + )) + } +
+
+ {commonSkills.ponytail.number}{commonSkills.ponytail.kind.en} +

{commonSkills.ponytail.title}

+ {commonSkills.ponytail.rule.en} +
+
+ {labels.commonSkill.whenToUse.en}

{commonSkills.ponytail.use.en}

+
+ {labels.commonSkill.example.en}

{commonSkills.ponytail.example.en}

+
+ {labels.commonSkill.watchOut.en}

{commonSkills.ponytail.caution.en}

+
+
{labels.commonSkill.source.en} +
+
+
+
+ INSTALL PACKAsk your coding agent to verify, install, and validate the skills. +
+ 
{install.en}
+ Review every source before installation. Existing local skills must be preserved. +
+
+
+ +
+
+ Hands-on10 minutes / one missing feature +
+
+

Tiny Tasks lab

+ Same task.
Better operating system. +

+
+

+ Start with a deliberately incomplete static task board. Run one prompt as written, + reset, then run the skill-enabled version. +

+ Open the starter →Open the rules lab → +
+
+
+
+
+
RUN AGood prompt
+ 
{handsOn.en.basic}
+ Clear context · constraints · acceptance · evidence +
+
+
+
RUN BGood prompt + skills
+ 
{handsOn.en.skills}
+ Same contract · explicit working methods · stronger proof +
+
+

+
+ + +
+
+ Verificationrun each gate separately +
+
+ 01 · STATIC

Lint and types

+ Format, lint, type-check. Fast and scoped to one file. +

pnpm lint; echo "lint=$?" +
+ 02 · BEHAVIOR

Unit and contract

+ Tests that repeat. Run before claiming done. +

pnpm test; echo "test=$?" +
+ 03 · INTEGRATION

Real UI and API

+ Drive the actual UI, API, or browser. +

pnpm check:ui; echo "ui=$?" +
+
+
+
+
+ Keep learning12 new readings + primary docs +

+ Go deeper with official documentation, production case studies, Medium, and practitioner + workflows. Rules and enforcement case study → + Skills review desk → + 12-part reading path → +

+
+
+ +