Product case study · November 19, 2026
Ask Claude Code to fix a CSV header hidden by a BOM
Reproduce a Python CSV header failure, give Claude Code a bounded repair task, and verify UTF-8 imports without stripping meaningful data or ignoring bad bytes.

Handle the optional UTF-8 signature at the decoding boundary, then test that the repair preserves field content and rejects invalid bytes.
The CSV visibly starts with name,note, but your Python importer says the name column is missing. Renaming the column in a spreadsheet seems to fix it until the next export arrives.
Before asking Claude Code to “clean the CSV,” inspect what the program actually reads. A UTF-8 byte-order mark, or BOM, can become an invisible prefix on the first header. This exercise gives the agent a small repair with a firm boundary: support UTF-8 files with or without that prefix, without rewriting the source or deleting characters from field values.
You need Bash on Linux, macOS or WSL, Python 3, and an installed, signed-in Claude Code. The Python fixture and reference repair below were tested locally; the Claude prompt is an authored exercise, not a recorded agent run. Official documentation was checked November 19, 2026.
Reproduce the missing header
Create a disposable directory containing only synthetic data:
csv_lab=$(mktemp -d /tmp/claude-csv-bom.XXXXXX)
cd "$csv_lab"
cat > reader.py <<'PY'
import csv
def read_contacts(path):
with open(path, encoding="utf-8", newline="") as stream:
reader = csv.DictReader(stream)
if reader.fieldnames != ["name", "note"]:
raise ValueError("expected name,note headers")
return list(reader)
PY
python3 - <<'PY'
from pathlib import Path
Path("contacts.csv").write_bytes(
b'\xef\xbb\xbfname,note\r\nAda,"review, then send"\r\n'
)
from reader import read_contacts
print(read_contacts("contacts.csv"))
PY
The last command raises ValueError. The header check is deliberately exact: this importer expects two columns in that order. Do not relax that requirement just to make the demo pass.
Inspect the file without changing it:
python3 - <<'PY'
import csv
from pathlib import Path
print(Path("contacts.csv").read_bytes()[:8].hex(" "))
with open("contacts.csv", encoding="utf-8", newline="") as stream:
print(repr(next(csv.reader(stream))[0]))
PY
The output is:
ef bb bf 6e 61 6d 65 2c
'\ufeffname'
Python’s codec reference describes ef bb bf as the optional UTF-8 signature. Ordinary UTF-8 decoding leaves the corresponding character in the string. The utf-8-sig decoder consumes it when it occurs at the beginning of the byte stream. It is not a general encoding detector.
The CSV reference explains that DictReader uses the first row as field names when no names are supplied. The parser therefore receives a different first header from the one your eyes see.
Define what the repair must preserve
Save this as SPEC.md:
read_contacts(path) reads a small comma-separated UTF-8 file.
Accept an optional single UTF-8 signature at the start of the file.
Require the exact headers name,note, in that order.
Return a list of row dictionaries; preserve field strings exactly.
Preserve commas and CRLF sequences inside quoted values.
Do not remove U+FEFF from inside a field value.
Reject invalid UTF-8 rather than replacing or ignoring bytes.
Do not modify the input file or write a cleaned copy.
Change only reader.py. Keep SPEC.md and test_reader.py fixed.
Use the Python standard library; no encoding guessing or dependencies.
This is a decoding repair, not a complete CSV validator. The exercise does not establish a policy for duplicate records, missing cells or extra cells. Those require separate acceptance criteria before you use the reader in a production import.
Save the following as test_reader.py. Each test writes its own temporary file and checks that reading it did not change its bytes, even when the reader raises an exception.
import tempfile
import unittest
from pathlib import Path
from reader import read_contacts
class ReaderTests(unittest.TestCase):
def read_bytes(self, raw):
with tempfile.TemporaryDirectory() as folder:
path = Path(folder) / "input.csv"
path.write_bytes(raw)
try:
return read_contacts(path)
finally:
self.assertEqual(path.read_bytes(), raw)
def test_plain_utf8(self):
self.assertEqual(
self.read_bytes("name,note\nZoë,café\n".encode("utf-8")),
[{"name": "Zoë", "note": "café"}],
)
def test_leading_signature(self):
self.assertEqual(
self.read_bytes(b"\xef\xbb\xbfname,note\nAda,ready\n"),
[{"name": "Ada", "note": "ready"}],
)
def test_quoted_comma_and_crlf(self):
self.assertEqual(
self.read_bytes(b'name,note\r\nAda,"first, check\r\nthen send"\r\n'),
[{"name": "Ada", "note": "first, check\r\nthen send"}],
)
def test_interior_feff_is_data(self):
self.assertEqual(
self.read_bytes("name,note\nAda,a\ufeffb\n".encode("utf-8")),
[{"name": "Ada", "note": "a\ufeffb"}],
)
def test_wrong_header_is_still_rejected(self):
with self.assertRaises(ValueError):
self.read_bytes(b"person,note\nAda,ready\n")
def test_invalid_utf8_is_rejected(self):
with self.assertRaises(UnicodeDecodeError):
self.read_bytes(b"name,note\nAda,\xff\n")
Run the baseline:
python3 -m unittest -v test_reader
In the local check, six tests ran: five passed and the leading-signature test errored with ValueError. That result isolates the defect. If your baseline differs, check the filenames and copy the byte escapes literally before asking the agent to make changes.
Give Claude a bounded debugging task
Start claude in this folder and paste:
Read SPEC.md, reader.py and test_reader.py.
Run python3 -m unittest -v test_reader and report the baseline.
Explain why the first header looks correct but fails the exact check.
Change only reader.py to satisfy the specification.
Do not edit tests, rewrite CSV files, install packages, commit or delegate.
Keep the exact header check and strict decoding errors.
Run the same tests after your repair and report the actual result.
Explain why your patch preserves U+FEFF inside field values.
Anthropic’s common workflows recommends giving Claude a reproducible bug and checking the fix. Review the active permissions and proposed commands; this prompt’s file boundary is an instruction, not a filesystem sandbox.
If the patch adds errors="ignore", it has traded a visible error for silent data loss. If it applies .replace("\ufeff", "") to the whole decoded file, it changes the interior-field test. If it splits lines or commas manually, it risks breaking the quoted value. Ask the agent to explain the failing requirement rather than approve a broad cleanup.
Inspect the small repair
The reference implementation changes only the encoding argument:
import csv
def read_contacts(path):
with open(path, encoding="utf-8-sig", newline="") as stream:
reader = csv.DictReader(stream)
if reader.fieldnames != ["name", "note"]:
raise ValueError("expected name,note headers")
return list(reader)
This reference passed all six tests locally. The optional signature is handled before CSV parsing; the header requirement remains unchanged. Keeping newline="" lets the CSV reader handle newline sequences, including the CRLF inside the quoted test field, as documented in the CSV reference.
Exit the agent session and verify independently:
python3 -m unittest -v test_reader
python3 - <<'PY'
from reader import read_contacts
print(read_contacts("contacts.csv"))
PY
The demo should now print:
[{'name': 'Ada', 'note': 'review, then send'}]
If it still reports the old header error, confirm that you edited the reader.py in the current folder. If a real export raises UnicodeDecodeError, stop and establish its encoding from the exporting system. Changing to a permissive codec until the exception disappears is not evidence that the text is correct.
You now have a specific acceptance record: plain UTF-8 and a leading UTF-8 signature work, quoted content survives, invalid bytes fail, and the reader leaves its input untouched. Keep that claim narrow. Passing these six cases does not establish that every spreadsheet export or CSV dialect is supported.
Sources
Checked November 19, 2026:
- Python: codecs — UTF-8 signature bytes,
utf-8-sigdecoding and strict error handling. - Python: csv — header mapping with
DictReaderand newline handling. - Anthropic: Common workflows — reproducible debugging and verification with Claude Code.
Put this to work
How to turn an invisible-character bug into a precise agent task with observable checks.
Try
Repair one Python CSV reader in a disposable folder.
Prove it worked
Run six tests before and after the change, including unchanged input bytes and invalid UTF-8.
Keep in view
- Reproduce a missing-header error with a tiny synthetic CSV.
- Separate a leading encoding signature from characters inside real fields.
- Keep acceptance checks fixed while Claude Code repairs the reader.