@yibie: Recommended article: Eugene Yan from Anthropic (former Amazon/Alibaba ML team lead) writes a practical guide to his personal AI workflow. Not abstract ideas, but concrete methods you can replicate tomorrow: how to organize directories for easier model retrieval, how to write C…

I recommend this article. Eugene Yan of Anthropic (former ML team lead at Amazon/Alibaba) has written a practical guide on his personal AI workflow. It’s not abstract theory—it’s specific methods you can copy tomorrow: how to organize directories so models can retrieve context more easily, how to write CLAUDE.md as a behavioral contract, how to turn weekly recurring tasks into skills, and how to have models “watch models” to prevent drift. The last sentence reveals another layer of this article—it’s not just a personal tool, but also a way to design agent harnesses, set team norms, and build organizational infrastructure.

How to Collaborate with AI and Make Work Compound

How do you collaborate effectively with AI? What does the workflow look like, how does it scale, and how do you improve your system over time? Ideally, it should compound—every finished artifact (code, documents, analysis, decisions) becomes context for the next session. Every correction updates a configuration, reducing future errors.

If you use AI frequently, you’re probably already applying many of these practices. But the underlying principles are universal: provide good context, encode your taste as configuration, make verification easy, delegate larger tasks, and close the feedback loop. If you look closely, you’ll notice these principles aren’t AI-specific—they’re simply how you “onboard and collaborate with any new teammate.”

Context as Infrastructure

Help the model navigate your context.

For example, all my code lives in ~/src, and all my knowledge work lives in ~/vault (organized into projects/, notes/, kb/, etc.). When work is organized, it’s easier for the model to retrieve context using grep or glob. A clean directory tree also makes it easier for the model to navigate, find, and rely on previous code, project documentation, and analysis to improve ongoing work.

Connect the model to your organization’s context.

Models can benefit from organizational knowledge—which often lives in Slack, Drive, email. Most platforms have corresponding MCP connectors. On top of that, I maintain a project-level INDEX.md. It’s an annotated index of relevant documents and channels, each with a URL, owner, and a short description. Annotation is critical—a bare list of URLs forces the model to open every link to figure out what’s relevant, wasting time and context. By annotating upfront, we get it done once.

Onboard each new session like a new hire.

Each new session, the model starts from a blank slate. So it’s very useful to treat the project-level CLAUDE.md like the onboarding document you’d give a new colleague on day one. Claude scanned my CLAUDE.md and found that among them there’s a glossary of abbreviations, project codenames, and ways to distinguish teammates with the same name. I also have a suggested reading order—tell the model to skim INDEX.md first, then TODOS.md, and finally topic-specific notes.

Build your memory layer.

By default, the model doesn’t remember what happened in the previous session, so anything worth persisting should be written to disk. I split my memory layer into two buckets. ~/vault stores facts: project status, artifacts, domain knowledge; ~/.claude (along with CLAUDE.md, skills/, guides/) contains my preferences, workflows, and personal taste—the former provides context, the latter provides configuration.

Taste as Configuration

Start with ~/.claude/CLAUDE.md.

Claude reads this at the start of every session. I see it as a behavioral contract. My CLAUDE.md includes preferences like how direct to be, when to push back, how to handle errors, how to teach me, and so on.

Layer by directory: global → repository → project.

Put preferences that apply everywhere (behavior, long-term goals, teaching style) in ~/.claude/CLAUDE.md. Put repository-specific conventions in the repo root. Put project-specific context (directory layout, domain knowledge) in the project directory. When you start Claude Code from a subdirectory, it walks up the tree, loading each CLAUDE.md.

When CLAUDE.md gets too long, split it out.

A too-long CLAUDE.md becomes a context tax. It loads everything every session, even if the session doesn’t need it. The solution is to refactor chunks into lazy-loaded guides. Don’t reference them directly inside CLAUDE.md (that would inline everything)—instead, tell it to “read when relevant.” That way, a session building evals skips the guide for writing documentation.

If you do something more than once a week, turn it into a skill.

A skill is a markdown file with a name, trigger words, and steps. Think of them as workflows written in markdown. They can contain logic. For example, my /polish skill looks at the artifact diff—if it produces a metric, it runs the eval; if it renders in a browser, it checks the output via Claude in Chrome; if neither, it runs the code and reads the output or error. Skills encode both the steps and the logic for deciding which steps apply.

Bootstrap skills by doing the task once, then asking the model to turn it into a skill.

This is how I build most skills. First, do the task interactively in a normal session. Then ask the model to turn what we just did into a skill. Next, run that skill on a similar or the same task. Inevitably, I need to correct the output—I correct it in the same session so the feedback is recorded in the transcript. Finally, ask the model to update the skill based on the corrections and feedback.

Refine skills via the transcript, not by editing the file directly.

The first version of a skill is rarely perfect because it overfits the original session. That’s normal. When you run it and need to correct the output, correct it within the session. Don’t open the file and edit SKILL.md. Providing feedback in the session gives the model before-and-after pairs—here’s what we did, here’s what I wanted, and why—which accumulate in the transcript. Once the output is right, ask the model to merge the feedback into the skill. After a few rounds, the skill converges and you hardly need to edit the final output.

Not every task needs this heavy context.

For brainstorming, exploration, and drafts, I like to use simple mode. CLAUDE.md still loads, but the agentic harness—hooks, skills, heavy tool loops—doesn’t run. This brings me closer to the model, which is the state I want when I’m thinking out loud rather than “delivering.”

Verification Drives Autonomy

Shift verification left; catch errors at write time.

I see verification as a ladder. The bottom is cheap and deterministic; the top is expensive and requires judgment. We want to solve problems at the lowest possible rung. Near the bottom are post-edit hooks that run ruff format on files the model just changed. This happens deterministically and consumes no tokens. Higher up are tests, evals, LLM reviews, and so on.

Make it easy for the model to verify its own work.

Give the model feedback loops to improve its output. If the system produces a metric, let the model run the eval and optimize it. If the artifact renders in a browser, let the model check it via Claude in Chrome. If neither, let the model run it and read the error. For example, when building a Docker image, I let the model build, read errors, edit the Dockerfile, and rebuild. If I’m tuning a harness, the model runs evals, reads transcripts, and fixes failures. When building a dashboard, the model checks in Chrome that tooltips render, labels don’t overlap, and the narrative matches the numbers.

For long tasks, have models watch models.

Long sessions can drift as errors accumulate. The solution is to run a secondary session with fresh context that reads the original spec and the most recent rounds of the primary session. My simplest setup is dual tmux panes—one primary dev, one pair programmer. Initial instructions and subsequent prompts are appended to a shared file. The pair programmer periodically starts up, checks the spec against the primary session’s transcript, and if it finds drift, provides feedback to correct direction.

This means checking two kinds of drift: execution drift (is the model doing the task correctly?) and direction drift (is the model doing the right task?). Check the former frequently and the latter occasionally.

Scale by Delegation

Delegate increasingly large chunks of work.

Sometimes we pair-program with models: short tasks, fast feedback. That works well for rapid iteration, exploratory analysis, and prototyping. But as models become stronger, we should aim to delegate larger tasks. Explain intent, constraints, and success criteria upfront, then let the model work. You can’t delegate what you can’t verify, so this requires first defining success criteria and metrics. The shift is from giving one instruction at a time to laying out a plan and letting the model execute end-to-end.

“Given these eval suites, build isolated containers for each suite, smoke test that each can be built. Then run them in full, recording eval metrics and transcripts. Use a sub-agent to read transcripts to confirm the evals ran correctly. Run each eval n times to get confidence intervals. Finally, generate a report, verify it matches the report guide, and slack me the results and report URL.”

Run sessions in parallel; find the bottleneck.

Delegating larger tasks means you can run multiple at once. I typically run 3–6 sessions simultaneously. The bottleneck has shifted from “doing” to “writing clear specs and quickly reviewing output to keep the pipeline flowing”—the middle is hollowing out. If parallel sessions share the same repo, use git worktree so each session gets its own checkout without overlapping.

Make sessions observable.

When running multiple sessions, I need to know the status of each and which needs attention. My stop hook plays a sound when a session completes. My tmux window titles use status emojis and short Haiku-generated labels to tell me what each pane is doing. Claude Code’s status bar shows context usage and current mode.

Check in while AFK.

Claude Code’s /remote-control makes this easy. While commuting or standing in line, use the Claude mobile app to open the code tab, see what’s running and what’s blocked, and unstick a stuck session if needed.

Close the Loop

Keep context rich by working in the open.

When we work in shared documents, repos, and channels, it makes it easier for everyone—including the model—to retrieve and benefit from context. What we share today becomes part of the organizational context tomorrow. Try this simple test: can a new teammate replicate your work from last week using only shared context? If yes, you’re contributing to organizational context. If no, that valuable context is stuck in your head. I automate part of this through instructions in CLAUDE.md—every time I complete a substantive task, I send a short update to the worklog channel with links to the artifact, PR, or document.

Mine your transcripts for configuration updates.

Have the model read past session transcripts to find gaps. When I scanned about 2,500 past user turns, a significant proportion contained phrases like “could you also…”, “did you check…”, “still not right.” These indicate what the model should have done without being prompted, and I should update CLAUDE.md or a skill, or note that a certain verification step is missing or broken. The frequency tells you how often it occurs, and the transcript shows exactly where the problem lies.

Regularly refactor and trim.

As configurations grow, they can overlap or conflict. If the model ignores a rule, it may be because another rule conflicts with it. Fix this by periodically refactoring. Each rule or preference should exist in only one place (though critical instructions can be repeated in the main CLAUDE.md). Also check for scattered directory-level settings.json files and merge them back into ~/.claude.

The specific setups will change as models get better, but the principles will remain relevant: provide good context, encode your taste, make verification cheap, delegate more, and close the loop. What we’re doing is cultivating a collaborator, one feedback at a time. And come to think of it, these principles apply just as well to collaborating with human teams.

Moreover, this isn’t just about personal tools. It’s also how you design agent harnesses, set team norms, and build organizational infrastructure. Try reading it again through those lenses.

Original: https://eugeneyan.com/writing/working-with-ai/

#AIworkflow #AgentEngineering #SkillPractice