How to Use This Book

This is a coding book. Reading without running is reconnaissance, not completion.

Use two copies of the code

The repository’s companion crates are finished reference answers. For the strongest learning loop:

1. create a scratch crate or branch;
2. type the day’s slice yourself;
3. run cargo check after each meaningful change;
4. read the compiler error before searching for a fix;
5. compare with the reference only after you have a hypothesis;
6. run the focused tests and then the wider regression suite.

Copying a complete file can make the build green without creating understanding.

Do not skip the broken run

Every day includes a deliberate failure. Before running it, write down:

• what input will be accepted;
• which type or invariant should reject it;
• whether any effect may have happened;
• what artifact or trace should remain;
• what exit status or terminal state you expect.

Then run it and explain any difference.

Required work is offline

Scripted models, frozen provider responses, deterministic embeddings, tiny numeric models, and media fixtures keep the required path reproducible. Live APIs and accelerators are extensions. When you add one, keep the offline adapter and its tests.

Never put secrets in source, fixtures, traces, screenshots, or copied commands. Load credentials from the environment at the program edge and fail clearly when absent.

Keep four artifacts

For every substantial experiment, save:

1. the exact input/eval identity;
2. the trace or manifest showing what the system saw and did;
3. the output plus validation result;
4. a short decision note with quality, latency, cost, limitation, and next step.

When to open a deep reference

Start from the project day. Open a reference chapter when you hit a real question: why did this borrow fail, how should cancellation propagate, what does a KV cache cost, or what evidence makes a tool effect complete? Return to the project and change code immediately after the deep dive.

Use the Deep Reference Map to find the right chapter.

Definition of done

A day is complete when you can run the normal path, reproduce the failure path, pass the focused tests, and explain the first responsible boundary without reading the answer. A project is complete when its artifact is useful, its risky behavior is bounded, and another person can reproduce the result.