Trust current source and capture design decisions

Tell the difference between basic memory and dangerous stale memory; Treat code as the source of truth with million-token snapshot contexts; Capture a design.md standard and generate multi-route structural variants.

Original source pages and recordings require authorized access. The full article text here is public.

The practice is grounding AI coding workflows in the live project instead of trusting stale memory. John recommends keeping memory simple with Markdown and straightforward retrieval, treating the code as the source of truth, using generated visual inspiration to produce a durable design.md, and creating disposable UI variants directly in the app so you can compare directions quickly and delete the losers.

Working outcomes

  • Tell the difference between basic memory and dangerous stale memory
  • Treat code as the source of truth with million-token snapshot contexts
  • Capture a design.md standard and generate multi-route structural variants

Concepts and consequences

Code as the Source of Truth

Project memory can be useful, but it drifts as the code changes. John’s main point is that trying to update memory on every commit can turn into a parallel maintenance problem, so the safest default is to make the agent look at the current code when implementation details matter.

Why it matters: It keeps agents from confidently acting on outdated assumptions and keeps the workflow tied to what actually exists in the repo.

Lightweight Markdown Memory

John still sees value in basic memory when it stays simple: Markdown files, simple RAG, and human-readable notes. The danger starts when memory becomes a second system that has to be kept in sync with a fast-moving codebase.

Why it matters: Good memory reduces repeated explanation; bad memory becomes stale documentation that misleads both humans and agents.

Large-Context Snapshots as a Possible Escape Hatch

John briefly floated million-token context windows as a possible way to take useful snapshots of codebases, but he explicitly framed it as something he had not really tried yet. In this lesson, it is a possible direction, not a proven replacement for memory.

Why it matters: The useful idea is that current code text is more trustworthy than detached summaries, but this section does not teach a full large-context snapshot workflow.

Design.md from Generated Inspiration

John demonstrated starting design work from an inspiration board made of generated images, not scraped sites. He selected visual directions, copied them into an AI prompt, asked Codex to create a hoodie company landing page, and showed the generated design.md with references, style DNA, colors, typography, layout, composition, shape, and motion.

Why it matters: It turns vague taste into a concrete design artifact that the agent can use to generate UI that follows a direction instead of producing a generic layout.

Throwaway Route Variants

Instead of building a heavy Storybook setup for every experiment, John often asks agents to generate multiple temporary routes or page copies using the same components with different styles. He compares them in the app with simple navigation, picks the best direction, and deletes the rest.

Why it matters: It supports fast visual exploration without creating another maintenance surface that has to be kept up to date.

Reference tools and resources

Inspiration Board

The generated visual inspiration board John used to select design directions and copy a structured prompt into AI tools.

Use when: Use it when you do not know what a UI should feel like yet and need generated visual references to guide a design.md.

Reference

Codex CLI

The local coding agent environment John used in the demo to create the hoodie company project, generate a design.md, and build the landing page.

Use when: Use it when you want an agent working directly against a local project for repo-aware coding and prototyping.

Reference

Recommendations and best practices

  • Keep memory files light, boring, and close to the repo; avoid building a second knowledge system that must be updated every time the code changes.
  • When implementation details matter, have the agent inspect the current code instead of trusting memory.
  • Treat large-context repo snapshots as an experiment John mentioned, not as a proven workflow from this lesson.
  • Start AI design work from concrete visual inspiration, then turn that inspiration into a design.md before asking the agent to build UI.
  • Use generated inspiration images as design references rather than scraping or copying existing websites.
  • Generate temporary route or page variants when exploring visual direction, compare them in the app, pick one, and delete the rest.

Practice and acceptance criteria

Practice treating the live repo as the source of truth, then turn generated visual inspiration into a design.md and fast, disposable UI variants.

Checklist

  1. Pick a small active repo and identify one task where stale memory could mislead an agent, such as routing, data fetching, auth, or component structure.
  2. Ask Codex or your coding agent to inspect the current files before proposing changes, then have it summarize the source-of-truth evidence.
  3. Create or trim a repo-local Markdown memory file so it contains only stable conventions, setup notes, and human-useful guidance.
  4. For a larger task, give the agent the relevant current files or source context directly instead of relying only on detached summaries.
  5. Draft a design.md with sections for references, style DNA, colors, typography, layout, composition, shape, and motion.
  6. Prompt the agent to generate 3 route-level or page-level UI variants from design.md, with simple navigation between them in the local app.
  7. Review the variants in the browser, promote the best one to the real route, and delete the temporary routes.

Stale Memory Audit

Difficulty: Easy

Find one existing project note, README section, or memory file that might be outdated. Ask the agent to compare it against the current code and produce a small patch that either fixes, shrinks, or deletes the stale guidance.

Done when: The repo has less misleading documentation, and the agent's recommendation is based on current files rather than remembered assumptions.

Design.md Landing Page Contract

Difficulty: Medium

Create a design.md for a fictional product landing page using concrete rules for references, style DNA, typography, color, layout, composition, shape, and motion. Then ask the agent to build one route from that contract.

Done when: The generated page visibly follows the design.md instead of feeling like a generic template.

Anti-Storybook Variant Sprint

Difficulty: Hard

Generate 5 disposable route-level variants of the same page from your design.md, add left and right arrow navigation, review them in the browser, promote the strongest version, and delete the other four.

Done when: Only the chosen implementation remains in the app, the rejected variants are removed, and the final route still follows the design contract.

Questions to test understanding

Your coding agent confidently says a project still uses an old routing structure, but you know the app has changed recently. What should you do first?

  • A. Ask the agent to rely on its saved memory because it has seen the project before.
  • B. Have the agent inspect the current repo or provide current source context before making changes.
  • C. Create a longer memory file describing the old routing structure in more detail.
  • D. Skip investigation and let the agent implement the change directly.

Answer: B. The live codebase is the source of truth when implementation details may have changed. Stale memory is most dangerous when it sounds confident but no longer matches the repo.

When is lightweight Markdown memory most useful in this workflow?

  • A. When it captures stable, human-readable guidance close to the repo.
  • B. When it replaces the need to inspect code for implementation-dependent tasks.
  • C. When it becomes a separate system that must be updated after every commit.
  • D. When it hides project knowledge inside an opaque retrieval pipeline nobody reviews.

Answer: A. John’s version of useful memory is simple: Markdown, straightforward retrieval, and information that remains useful to humans. The moment it becomes a parallel system to maintain, it starts creating the stale-memory problem.

Why did John emphasize that the inspiration board images were generated rather than scraped?

  • A. Because the workflow is about getting visual direction without copying live websites directly.
  • B. Because scraped websites cannot be used by AI tools at all.
  • C. Because generated images remove the need for design review.
  • D. Because the inspiration board is only meant for backend architecture planning.

Answer: A. John used generated images as inspiration material: something to look at when deciding what the UI should feel like. The point was to guide direction, not clone an existing site.

What job does design.md perform in this lesson's AI design workflow?

  • A. It stores every rejected mockup so the agent can reuse them later.
  • B. It acts as a reusable design brief covering references, style DNA, typography, color, layout, composition, shape, and motion.
  • C. It replaces visual review because the agent can infer the best design automatically.
  • D. It is only useful for copying an existing website exactly.

Answer: B. design.md turns selected visual inspiration into reusable instructions the agent can build from. John showed Codex using the design document and reference files to produce a workable hoodie landing page direction.

Why generate throwaway route-level variants instead of immediately building a full Storybook-style setup?

  • A. Because variants should become permanent maintenance surfaces.
  • B. Because route variants avoid needing to review the UI in a browser.
  • C. Because agents cannot generate components directly.
  • D. Because you can compare real layouts quickly in the app, pick a winner, and delete the rest.

Answer: D. John favors quick prototyping directly inside the app when he is not being disciplined about a full design system. Temporary routes are useful only if the losing experiments are cleaned up.

Reflection prompts

  • Where does your current workflow still ask agents to trust memory when they should inspect the live code instead?
  • What project knowledge is stable enough to live in Markdown, and what knowledge changes too often to be trusted outside the code?
  • What visual references and style details would make your design.md specific enough for an agent to build from?

Further applications

  1. Create a small design.md template with sections for references, style DNA, colors, typography, layout, composition, shape, and motion.
  2. Run the anti-Storybook exercise: generate several landing page routes, add left/right arrow navigation, pick one, and remove the rest.
  3. Try a small current-code snapshot experiment: give the agent the relevant current files for one task and compare the result to an answer based only on an old memory note.
  4. Write a reusable prompt that asks the agent to inspect the current code first, summarize the source-of-truth evidence, and only then propose or implement a change.

Applied exercises

Exercise: Variant Navigation Pattern (The Anti-Storybook Method)

Objective: Build a rapid visual alternative to heavy interface sandboxes by spawning page variants directly inside an active dev server environment.

Task Parameters: Create a prototype folder and initialize a workspace using your agent framework.Prompt your model tool to generate 3 to 5 discrete variations of a landing layout block, rendering them as raw inline HTML implementations within adjacent testing folders.Program a basic temporary navigation wrapper into the page footers (e.g., binding standard Left Arrow and Right Arrow key actions) to switch seamlessly between layout iterations.Review your layout choices directly inside your active browser view. Once you select a winning design pattern, instruct your agent runner to delete the temporary variants and promote the chosen layout to your core project file path.

Questions and answers

Are you using the memory features of these harneses? I noticed they get out of date when I use them and shifted to beads but even that has some clunk still https://github.com/gastownhall/beads

Memory systems frequently run out of date because the underlying codebase is the ultimate source of truth. Attempting to continuously update external memory stores on every commit quickly turns into an administrative bottleneck. John suggests keeping project memories as lightweight as possible. He also mentions an alternative: leveraging large context allowances (like Oracle's 1 million token limit) to pass raw codebase snapshots directly into the context window, bypassing the need for explicit memory stores.

I use basic memory that i got from you a while back, I still find it to be an excellent tool, I like to use it to keep things documented for developers within the same repository, would love to know if you still use it, and for what purpose, I know karpathy popularized simple, obsidian graph knowledge as opposed to a rag vector retrieval, basic memory seems to have best of both worlds

John agrees that basic memory approaches that rely on simple Markdown file formatting combined with straightforward RAG mechanisms work well because they avoid unnecessary over-engineering. He notes that unless an advanced automated context synchronization system emerges, keeping documentation minimal and close to the raw source files remains the most practical path forward.

Were you ever a fan of warp terminal? This cmux looks like I might be able to get rid of that subscription!

John used Warp for a short period but eventually ran into specific workflow limitations. Certain built-in keyboard shortcuts and essential macro behaviors were unsupported at the time, leading him to return to terminal workflows like cmux. He notes that Warp has since moved open-source, and mentions he would gladly return to any terminal harness layer if it becomes highly agentic, performant, and serves his user experience goals better.

This is a little off topic but when generating a lot of research what guiding principles do you reach for to staying organized as well as optimize for the ai’s retrieval ?

The question continues into the perspective-based research discussion: assign expert, new-user, grandparent, and power-user lenses to separate workstreams, then use numbered QA assignments to make the results targeted and retrievable.

Operational playbooks

Recording references

Timestamped source page

Visual reference index

  • 01:23:45: Browser screen shot demonstrating multiple layout panels stacked on the inspiration-board application interface.
  • 01:26:14: Selection highlight highlighting layout component segments prior to executing copy commands.
  • 01:27:19: Terminal window capturing structural parameters pasted cleanly into the main prompt console input field.
  • 01:28:55: Editor viewport capturing structural variables mapping colors and typography metrics inside the design.md file.
  • 01:31:16: Dual terminal workspace capture displaying secondary script workers generating page instances side-by-side.
  • 01:33:30: Terminal display capturing structural prompt bypass responses responding to systemic skip trust flags.
  • 01:34:50: Live interface preview screen showcasing vector hoodie styling data compiled via background generation passes.
  • 01:37:45: Terminal logs showing completed codebase outputs verifying final production code frameworks.

Source references