Initial commit: coding-with-ai

A practical guide to working effectively with AI coding assistants
(chat interfaces, in-editor extensions, agentic tools) for engineers
and scientists solving problems with code rather than building
production software.

Seven sections:

- 01-three-modes: web chat vs in-editor vs agentic, with heuristics
  for choosing and a framing of chat as natural-language programming.
- 02-errors-and-logs: the canonical copy-paste case; framing the
  paste for useful answers.
- 03-in-editor-workflow: autocomplete, inline edit, side panel,
  quick actions; habits that survive tool changes.
- 04-conversations: multi-turn discussions, context-window
  awareness, opening well, prompt iteration, when to start fresh.
- 05-agentic-workflow: variations on the basic loop (sub-agents,
  plan mode, async, MCP, sandboxing); briefing, supervision,
  damage control, cost and energy.
- 06-verifying-and-citing: hallucinations and silent errors;
  privacy framed against the cloud-services baseline; proportional
  disclosure norms.
- 07-local-models: local models as a cross-cutting alternative
  across all three modes; hardware tiers, tool support,
  capability gap.

Tool-agnostic where possible; current tool examples are
illustrative and expected to date.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

03-in-editor-workflow/README.md

@@ -0,0 +1,88 @@
+# In-Editor Workflow
+
+## Key idea
+
+Editor extensions are best used as a tight feedback loop: small suggestions, surgical edits, fast accept/reject decisions. The point is not to "let the AI write code for you." The point is to remove the keystrokes that don't deserve your attention while keeping the keystrokes that do.
+
+## Key goals
+
+- Recognize the four common in-editor patterns: autocomplete, inline edit, side-panel chat, quick actions
+- Use each pattern for the kind of work it suits
+- Develop habits that keep you in control of what lands in your code
+- Know when to escalate to a chat, an agent, or just write it yourself
+
+---
+
+## Four patterns
+
+In-editor AI extensions (GitHub Copilot, Claude for VS Code, Codeium, Microsoft Copilot, Cursor's built-in features) vary in keystrokes and naming, but most expose the same four patterns. Learn the patterns; the keystrokes will follow.
+
+### 1. Autocomplete (ghost text)
+
+As you type, the extension proposes the next few tokens or lines as faint "ghost text." You accept with Tab (typically) or keep typing to ignore.
+
+**Best for:** boilerplate you would have typed anyway. Loop scaffolds, function signatures whose shape is obvious, import lines, the body of a getter, repetitive variations of the same pattern.
+
+**Habit to build:** *read the suggestion before accepting it.* The cost of accepting wrong code that looks right is high — you'll find the bug an hour later in a debugger when you could have caught it in 200 milliseconds. If a suggestion is more than a few lines, the right move is usually to read it, decide, and either accept or rewrite. Do not Tab-and-pray.
+
+**Habit to break:** *do not autocomplete your verification.* Whether your verification is a formal unit test, a sanity-check script, or a comparison against a known answer, it is supposed to be *your* expression of what the code should do. If the model writes the check based on the code, the check passes by construction and confirms nothing. Write your check yourself; let the model help with the implementation.
+
+### 2. Inline edit (edit-this-selection)
+
+You highlight a block of code and invoke the AI with a brief instruction: *"rewrite using a list comprehension,"* *"extract the inner loop into a helper,"* *"add type hints."* The extension shows a diff; you accept or reject.
+
+**Best for:** surgical edits with a clear before/after. Refactors, type hint additions, adding docstrings, converting between equivalent forms, applying a stylistic change consistently.
+
+**Habit to build:** *think of the instruction as a one-line spec.* The clearer your instruction, the better the diff. *"Make this better"* is a worse prompt than *"split this into a parse step and a validate step, keeping the same return signature."*
+
+**Habit to break:** *do not invoke inline edit on a block you do not understand.* If you cannot evaluate the diff, you cannot reject a bad one. Skim or read the block first.
+
+### 3. Side-panel chat (with file or project context)
+
+A chat window in your editor where you can ask questions and the extension attaches whatever files or selections you've referenced. Some extensions auto-attach the open file; others require you to add context explicitly.
+
+**Best for:** *"explain this function," "why is this slow," "how would I extend this to do Y,"* — questions where the answer is words, not a direct edit, but where you want the answer informed by your actual code rather than a generic snippet. Side panels have matured to the point where they also handle **multi-turn design discussions well**, especially when the discussion is anchored in files you have open — the one-click attachment of files and selections is a real advantage over alt-tabbing to a web chat.
+
+**Habit to build:** *be explicit about what context you want included.* If the extension lets you pin specific files or selections to the conversation, use it. The model can only reason about what it sees.
+
+**When to step out to a web chat instead:** the discussion needs to outlive the editor session (a record you want to return to days later), needs to include collaborators who don't share your editor, or pulls in lots of non-code context (papers, third-party docs, screenshots). See [section 04: Conversations](../04-conversations/) for those patterns.
+
+### 4. Quick actions (rename, extract, add types)
+
+Many extensions surface "intelligent" versions of classic IDE operations: rename a symbol across a file or project, extract a selection into a function, add type hints to a function signature.
+
+**Best for:** classic refactors you would otherwise do by hand, with an AI doing the renaming or signature work. These are usually safe because the change set is small and visible.
+
+**Habit to build:** *check the scope.* "Rename across project" can change more than you expect — make sure you reviewed the file list or used a version-controlled state you can roll back from.
+
+
+## When to escalate
+
+In-editor extensions are great inside their lane. Recognize when to step out of it:
+
+| Symptom | Escalate to | Why |
+|---|---|---|
+| The conversation needs to outlive this editor session, be shared with collaborators, or pull in non-code context | Web chat ([section 04](../04-conversations/)) | Web chats persist, share, and accept arbitrary content more easily |
+| The edit you want spans many files | Agent ([section 05](../05-agentic-workflow/)) | Inline edit is per-file; agents handle cross-file work |
+| You keep tabbing through bad suggestions for the same task | Write it yourself | The model doesn't have enough signal; you are faster |
+| The output is large and the result needs verification | Write it yourself or pair with your own checks | Trust-but-verify gets expensive at scale |
+
+
+## Habits that survive tool changes
+
+The tools will keep changing. These habits do not:
+
+- **Read every accepted suggestion.** Even autocompletes. Especially autocompletes.
+- **Keep the cycle tight.** If the model is producing more than ~20 lines at a time without your review, you are no longer in the loop.
+- **Use version control as a safety net.** Commit before any large AI-assisted change. `git diff` is the last line of defense.
+- **Verify with your own checks.** Whether that means a formal test, a script that compares against a known answer, a plot you eyeball, or a hand calculation depends on what you are writing. The check has to come from you, not from the AI that wrote the code.
+- **Be willing to write code yourself.** The AI is a tool, not a substitute for understanding what you're building.
+
+
+## Exercises
+
+> **Exercise 1:** For one work session, keep autocomplete on but make a conscious "accept / reject / rewrite" decision on every suggestion of more than one token. Note how often each happens. The exercise is not "reject more" — it is to make the choice visible.
+
+> **Exercise 2:** Take a function in a recent project and use inline edit three times with three different instructions: a vague one (*"make this better"*), a specific one (*"split into parse and validate steps"*), and a constraint one (*"refactor to remove the nested if"*). Compare the diffs.
+
+> **Exercise 3:** Try a "no AI for one task" experiment: pick a small feature, write it yourself with the extension disabled. Then re-enable and use it for a comparable second feature. Note where the AI saved you time, where it cost you time, and where the difference was negligible.