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>
This commit is contained in:
Eric Furst
commit
5780cdf097
9 changed files with 958 additions and 0 deletions
146
02-errors-and-logs/README.md
Normal file
146
02-errors-and-logs/README.md
Normal file
|
|
@ -0,0 +1,146 @@
|
|||
# Errors and Logs
|
||||
|
||||
## Key idea
|
||||
|
||||
Errors, stack traces, and log output are *exactly* the kind of thing chat models excel at parsing. A transformer's attention is built for finding the relevant token among noise. Use it!
|
||||
|
||||
Errors and logs are the canonical copy-paste use case. The trick is pasting *enough* context but not *too much*, and being explicit about what you were trying to do.
|
||||
|
||||
## Key goals
|
||||
|
||||
- Recognize when a chat is the right tool for an error or log
|
||||
- Paste the right amount of context — neither too little nor too much
|
||||
- Frame the paste so the model can give a useful answer, not a guess
|
||||
- Use the answer as a starting point, not gospel
|
||||
|
||||
---
|
||||
|
||||
## Why chat is the right mode here
|
||||
|
||||
A typical Python traceback is 10–40 lines of mostly-noise with one or two lines of actual signal. A 500-line server log has maybe three lines that matter. Two reasons chat works here:
|
||||
|
||||
1. **The output is words, not code-in-place.** You are looking for an explanation or at least a pointer, not an edit to a file. Chat is the stronger choice.
|
||||
2. **The input is self-contained.** You can paste the whole error and the model can reason about it without needing your project layout, history, or build state.
|
||||
|
||||
In-editor extensions can also handle errors (most have "explain this error" features), and that is fine for small ones. But for a long traceback or a multi-page log, chat's room to expand and your ability to copy-paste freely makes it the better tool.
|
||||
|
||||
## What to paste
|
||||
|
||||
Three rules:
|
||||
|
||||
### 1. Paste the whole relevant block, not just the last line
|
||||
|
||||
The first line of a Python traceback ("File X, line Y, in foo") matters as much as the last line ("ValueError: ..."). Most stack traces tell a small story: *here's the path the program took to reach the error.* The model needs the path, not just the destination.
|
||||
|
||||
**Bad:**
|
||||
|
||||
```
|
||||
ValueError: cannot convert string to float
|
||||
```
|
||||
|
||||
**Better:**
|
||||
|
||||
```
|
||||
Traceback (most recent call last):
|
||||
File "analyze.py", line 47, in <module>
|
||||
df["temp"] = df["temp"].astype(float)
|
||||
File ".../pandas/core/series.py", line 5816, in astype
|
||||
...
|
||||
ValueError: could not convert string to float: 'N/A'
|
||||
```
|
||||
|
||||
The second version makes the cause (the string `'N/A'` in the data) obvious. The first leaves the model guessing.
|
||||
|
||||
### 2. Trim noise that doesn't help
|
||||
|
||||
A 2000-line log with five relevant lines is harder for the model (and you) than 50 lines centered on the relevant region. Use `grep`, `tail`, or your eyes to narrow it down. Include enough surrounding context that the model can see the lead-up to the failure, but cut the parts that are clearly unrelated (startup banners, unrelated services, repeated heartbeat lines).
|
||||
|
||||
If you do not know which part is relevant, paste a reasonable chunk and *say so*: "I think the failure is somewhere in here but I'm not sure where to look."
|
||||
|
||||
### 3. Include the command or code that triggered it
|
||||
|
||||
The model can analyze a traceback in a vacuum, but answers improve a lot when it knows what you were running. Even a single sentence helps:
|
||||
|
||||
> "I ran `python analyze.py temperatures.csv` and got this:"
|
||||
|
||||
That tiny preamble lets the model relate the error to the code path you exercised.
|
||||
|
||||
## What to say *around* the paste
|
||||
|
||||
A useful pattern is three short lines plus the paste:
|
||||
|
||||
> What I was trying to do.
|
||||
> What I expected to happen.
|
||||
> What actually happened (with the paste).
|
||||
|
||||
For example:
|
||||
|
||||
> I'm trying to load a CSV of furnace temperatures into a DataFrame and convert the temperature column to float. I expected the conversion to work. The file looks clean. Instead I'm getting this:
|
||||
>
|
||||
> ```
|
||||
> Traceback ...
|
||||
> ValueError: could not convert string to float: 'N/A'
|
||||
> ```
|
||||
|
||||
This is enough for the model to land on the right answer (some rows have `'N/A'` strings) and suggest the right fix (handle the missing values explicitly).
|
||||
|
||||
If you've already tried things, say so. *"I tried `pd.read_csv(..., na_values='N/A')` and it didn't change the error."* This saves the model from suggesting what you already ruled out.
|
||||
|
||||
## What to do with the answer
|
||||
|
||||
The model's first answer to an error is often *plausible but wrong about the root cause*. It will identify the right neighborhood — "there is a non-numeric value in your column" — but may guess wrong about the specific row or the fix that works in your case. Treat the answer as a **search query**, not a firm result:
|
||||
|
||||
- Does the diagnosis match what you see in your data or code?
|
||||
- Is the suggested fix one you can verify quickly (one line, one test)?
|
||||
- If a suggested fix doesn't work, *say so* in the next turn and paste the new output. The second answer is usually much better because the first one ruled out a possibility.
|
||||
|
||||
The biggest mistake students make with chat-based error help is **treating the first response as authoritative**. The right mental model is: the model gives you a focused hypothesis, but you do the verification.
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
- **Pasting only the last line of the traceback.** The model can guess, but it's a guess. Paste the whole traceback.
|
||||
- **Pasting a 2000-line log unfiltered.** The model wastes attention on irrelevant material and the answer suffers. Trim.
|
||||
- **Pasting code with no error message.** "Why doesn't this work?" without the actual failure makes the model invent failure modes. Always run the code and paste what happened.
|
||||
- **Pasting proprietary code into a public chat.** See [section 06](../06-verifying-and-citing/) — what you paste, the service sees and may log. Match the chat to the sensitivity of the content.
|
||||
- **Not iterating.** If the first answer is wrong, the second is usually better. Treat the conversation as a debugging session, not a single oracle query.
|
||||
|
||||
## A worked example
|
||||
|
||||
You run a script and see:
|
||||
|
||||
```
|
||||
$ python train.py
|
||||
Traceback (most recent call last):
|
||||
File "train.py", line 12, in <module>
|
||||
model = model.to("cuda")
|
||||
File ".../torch/nn/modules/module.py", line 1145, in to
|
||||
return self._apply(convert)
|
||||
File ".../torch/nn/modules/module.py", line 797, in _apply
|
||||
module._apply(fn)
|
||||
...
|
||||
RuntimeError: Found no NVIDIA driver on your system. Please check that you
|
||||
have an NVIDIA GPU and installed a driver from http://www.nvidia.com/Download/index.aspx
|
||||
```
|
||||
|
||||
**A bad prompt:**
|
||||
|
||||
> Why doesn't my code work? `RuntimeError: Found no NVIDIA driver`
|
||||
|
||||
**A better prompt:**
|
||||
|
||||
> I'm running a PyTorch training script on my laptop. I expected it to fall back to CPU if no GPU was available, but instead I'm getting this. Is there a way to make the script run on whatever device is available? Here is the full traceback:
|
||||
>
|
||||
> ```
|
||||
> [full traceback as above]
|
||||
> ```
|
||||
|
||||
The better prompt gets you a useful answer about the standard `device = "cuda" if torch.cuda.is_available() else "cpu"` pattern, with the specific fix for line 12 of your script. The bad prompt gets you a generic "install NVIDIA drivers" answer that doesn't help you on a laptop without an NVIDIA GPU.
|
||||
|
||||
|
||||
## Exercises
|
||||
|
||||
> **Exercise 1:** Find a recent error you debugged. Reconstruct a "bad paste" (last line only, no context) and a "good paste" (whole traceback, what you were doing, what you expected). Try both in a chat. How different are the answers?
|
||||
|
||||
> **Exercise 2:** Take a log file from a real system you have run — even just a `pip install` that warned about something. Paste 50 lines unfiltered, then paste a `grep`-narrowed version of the same log. Compare the responses for usefulness.
|
||||
|
||||
> **Exercise 3:** Pick a real error and run a multi-turn debugging session. Paste the error, try the suggested fix, paste the new output, and continue until the issue is resolved or you understand why it cannot be. Note where the model's hypothesis shifted between turns.
|
||||
Loading…
Add table
Add a link
Reference in a new issue