d2ca02bd90
Restructures section 01 from "web chat / in-editor / agentic" into "web chat vs. tools that live with your code," with the autocomplete / in-project chat / agentic spectrum as a sub-structure of the latter. Inline edits are reduced to a historical note tied to the 2023 instruction-tuned LLM era. - Rename 01-three-modes -> 01-two-worlds and 03-in-editor-workflow -> 03-autocomplete; section 03 narrows to autocomplete (ghost text habits, the autocomplete-your-verification trap) - Section 04 reframes in-project chat as the default venue, web chat as a special-case venue; adds "Carrying context across sessions" covering dev-log.md, CLAUDE.md, .cursorrules - Section 05 reworks intro to contrast against in-project chat instead of "editor extension"; tightens prose and removes em-dashes - Update cross-references and tool-mode language in 02, 06, 07, and the root README to match the new framing - Swap the CRDT example in section 04 for finite-volume methods, fitting the CHEG audience - Minor typo/wording fixes Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
113 lines
8.6 KiB
Markdown
113 lines
8.6 KiB
Markdown
# Two Worlds
|
||
|
||
## Key idea
|
||
|
||
Most people meet AI assistance through web chat: open a browser tab, paste in a problem, copy the answer back. That works for one-shot questions, but it is the wrong tool for actually writing code. The goal of this guide is to move you off the copy-paste habit and onto tools that live with your code.
|
||
|
||
There are really only two worlds worth distinguishing:
|
||
|
||
1. **Web chat** — a browser tab. The AI has no awareness of your project.
|
||
2. **In your editor or terminal** — the AI lives where your code does. It can read your files, change them directly, and often run commands too.
|
||
|
||
The first is useful for explanation, interpretation, and sometimes planning. The second is what you want to use for any actual coding work.
|
||
|
||
## Key goals
|
||
|
||
- Distinguish web chat from tools that live with your code, and recognize which one your current task wants
|
||
- Recognize the spectrum *within* world 2: autocomplete, in-project chat, and delegated agentic work
|
||
- Stop treating the browser tab as your default coding workspace
|
||
|
||
---
|
||
|
||
## World 1: Web chat
|
||
|
||
A browser- or app-based conversation with a model. You type, paste, or drag content in and the model responds in the same window.
|
||
|
||
**Examples (early 2026):** ChatGPT, Claude.ai, Gemini, Microsoft Copilot (web). Each has a free tier with usage limits, a paid plan that removes those limits, and (often) institutional access through a university or employer agreement. You can also self-host a chat interface against a local model. See [section 07](../07-local-models/).
|
||
|
||
**What it's good at:**
|
||
|
||
- One-shot interpretation: *explain this error, what does this log mean, what does this regex match*
|
||
- Multi-turn design discussion: *"I'm choosing between approach A and B, what should I think about?"*
|
||
- Non-code work: drafting documentation, writing commit messages, explaining a concept
|
||
- Content you do not want the AI to "live in" — a snippet from a paper, output from a server you don't own, a script from an unfamiliar repo
|
||
|
||
**Weaknesses:**
|
||
|
||
- It's disconnected from your project. The model is stateless and has no idea what files exist, what your conventions are, or what you changed five minutes ago, unless you paste it in.
|
||
- Round-trip friction: copy from terminal → paste into chat → wait → read → copy answer → paste back. Fine for one-shot, painful for iterative editing.
|
||
- You have to remember to bring the relevant context with you every time.
|
||
|
||
**The trap:** because web chat was the first interface most people learned, it becomes their default. If you find yourself pasting code back and forth between a browser tab and your editor more than a couple of times in a session, you are using the wrong tool.
|
||
|
||
|
||
## World 2: AI that lives with your code
|
||
|
||
An AI assistant inside your editor or terminal that can see your files and change them directly. The interface might be a side panel where you chat, a CLI you type into, an autocomplete that fills in code as you type, or some combination, but the common aspect is that the tool *lives where the code lives*.
|
||
|
||
**Examples (early 2026):** Claude Code (CLI, VS Code, JetBrains), Cursor, Windsurf, GitHub Copilot, Cline, Aider, Microsoft Copilot agent. Most modern tools combine multiple interaction patterns in one package.
|
||
|
||
**Why this is the world to learn:**
|
||
|
||
- No copy-paste: the tool reads the file you're working on directly
|
||
- The model can see your project's actual structure and conventions
|
||
- Edits land in the file as a *diff* (a side-by-side view of what's being added, removed, or modified) that you review, not as text in a chat window you have to copy back
|
||
- The same tool can answer a quick question, make one targeted change, or run a multi-step task. You decide which by how or what you ask.
|
||
|
||
|
||
### The spectrum within world 2
|
||
|
||
A single tool that lives with your code can be operated three different ways. Modern tools (Claude Code, Cursor) support all three; older ones (vanilla Copilot, c. 2024) support only the first.
|
||
|
||
**1. Autocomplete.** Ghost text suggesting the next few lines as you type. You stay in the driver's seat keystroke by keystroke; the model just predicts what comes next. Cheap, fast, and easy to ignore when wrong. This is covered in [section 03](../03-autocomplete/).
|
||
|
||
**2. In-project chat.** A side panel or terminal session where you have a conversation that's aware of your files. You can ask design questions, request a targeted change, or ask the AI to explain something without leaving your editor. This is what you are doing if you are using Claude Code in a VS Code panel. We cover this in [section 04](../04-conversations/).
|
||
|
||
**3. Delegated agentic work.** You give the AI a multi-step goal, such as *"find where X is defined and update all the callers, then run the tests,"* and it runs the loop by reading files, making changes, running tests, reading the output, and fixing as it goes. You set the goal, but the agent runs the steps. We will review this in [section 05](../05-agentic-workflow/).
|
||
|
||
The line between (2) and (3) is fuzzy, and that's fine. A chat with an in-project AI *becomes* agentic the moment you ask it to do something multi-step. They are not separate tools, but are instead different ways of operating the same tool. The question to ask yourself is not "which mode am I in?" but "what am I asking for right now?"
|
||
|
||
|
||
### A historical note: inline edits
|
||
|
||
A fourth pattern, central to the Copilot/Cursor era of 2023–2024, is the **inline edit**: highlight a block of code, press a hotkey (Cmd+K in Cursor, "Edit with Copilot" in VS Code), type *"make this async"* or *"add error handling,"* and a diff appears in place. There is no chat, no agent loop, just one selection, one instruction, and one diff.
|
||
|
||
Inline edits emerged in 2023 alongside instruction-tuned LLMs (ChatGPT, GPT-4) — the first models that could reliably take a natural-language instruction and produce a corresponding code transformation. They sat between the earlier completion-only era (autocomplete, powered by Codex and similar) and the agentic loops that followed. As tools became agentic, the pattern has faded: you can do the same thing by asking the in-project chat *"switch the function I have highlighted to async,"* and the result is the same diff. Newer users may skip the inline-edit hotkey entirely. We mention it so you recognize what older tutorials are describing, not as a workflow you need to learn from scratch.
|
||
|
||
|
||
## How to choose
|
||
|
||
Two questions cover almost every case:
|
||
|
||
1. **Should the answer be words I'll read, or code that should land in a file?**
|
||
- Words → either world works
|
||
- Code → use world 2; world 1 forces a copy-paste loop
|
||
2. **Do I want the AI to be able to act on this content?**
|
||
- Yes, then use world 2
|
||
- No (sensitive snippet, untrusted code, output from a server you don't own), then world 1 is safer because the tool isn't wired to your filesystem
|
||
|
||
### Starting heuristic
|
||
|
||
| If the work is... | Use... | Why |
|
||
|---|---|---|
|
||
| Explain an error, parse a log, interpret some output | Either world | Words-out, no edit needed; pick whichever is open |
|
||
| Anything that should result in code landing in a file | World 2 | Removes the copy-paste round trip |
|
||
| A targeted edit you can describe in one sentence | In-project chat (world 2) | Fast, low-overhead, you read the diff before accepting |
|
||
| Multi-step work — cross-file changes, run-tests-and-fix loops, "explore the project and then change it consistently" | Delegated agent (world 2) | The model owns the sequence; you set the goal and review the end state |
|
||
| Reviewing or thinking through code you do not want the AI to act on | Web chat (world 1) | The tool can read but not edit |
|
||
| Deciding between two approaches; talking through a design | Either world | Conversation UX is what matters |
|
||
|
||
|
||
## Two principles underneath
|
||
|
||
**Match the mode to the output target.** If the answer should *be code in a file*, use a tool that can put it there. If the answer should be a conversation, either approach works.
|
||
|
||
**Match the mode to the iteration speed.** One-shot interpretation matches well with a chat. If you need a tight feedback loop on a known file, then in-project chat, no agent loop needed. For a multi-step plan you would rather not babysit step by step, use an agent.
|
||
|
||
|
||
## Exercises
|
||
|
||
> **Exercise 1:** Think of three recent times you used an AI assistant. For each, ask: did the work involve copy-pasting code into or out of a browser tab? If yes, what tool could have done the same job in-place?
|
||
|
||
> **Exercise 2:** Pick one in-project AI tool you have access to (Claude Code, Cursor, Copilot, etc.). Use it for everything code-related for one week — no browser chat for coding tasks. Keep a one-line note of where it fell short. Those gaps are where web chat is still the right tool.
|
||
|