Product case study · November 17, 2026
Ask Claude Code why identical-looking filenames do not match
Reproduce a Unicode filename mismatch with Claude Code, normalize comparison keys and catch ambiguous matches without renaming or deleting files.

Normalize the comparison key, preserve the original name and stop on ambiguity. A prettier string is not permission to overwrite a file.
An export lists café.txt. Your import asks for café.txt. The lookup still says the file is missing. Before asking an agent to rename anything, check what those strings contain: the accent can be part of one character or a separate combining character.
This lab gives Claude Code a small matching bug with an awkward second requirement: if two names become equivalent, it must stop rather than pick one. That collision check is what makes the repair useful for an import workflow.
You need Python 3, Bash on Linux, macOS or WSL, and an installed, signed-in Claude Code. The examples are fictional filename strings; they never create or rename the represented files. The baseline and reference implementation were tested locally. The agent prompt is an authored exercise, not a recorded Claude session. Official sources were checked November 17, 2026.
Expose the invisible difference
Run this in a terminal:
python3 - <<'PY'
a = "caf\u00e9.txt"
b = "cafe\u0301.txt"
print(a == b)
print(ascii(a))
print(ascii(b))
PY
The result is:
False
'caf\xe9.txt'
'cafe\u0301.txt'
The first string uses U+00E9; the second uses U+0065 followed by U+0301. Python’s Unicode HOWTO explains why displayed text and the underlying sequence of code points are different things. Copying what you see from a terminal can hide the clue. Explicit escapes make the reproduction portable.
Build a matcher with a visible failure
Create a fresh practice folder:
unicode_lab=$(mktemp -d)
cd "$unicode_lab"
cat > matcher.py <<'PY'
def find_name(names, requested):
matches = [name for name in names if name == requested]
if len(matches) > 1:
raise ValueError("ambiguous filename")
return matches[0] if matches else None
PY
Save this as test_matcher.py in the same folder:
import unittest
from matcher import find_name
class FilenameMatching(unittest.TestCase):
def test_exact(self):
self.assertEqual(find_name(["notes.txt"], "notes.txt"), "notes.txt")
def test_empty(self):
self.assertIsNone(find_name([], "notes.txt"))
def test_decomposed_inventory(self):
original = "cafe\u0301.txt"
names = [original]
self.assertEqual(find_name(names, "caf\u00e9.txt"), original)
self.assertEqual(names, [original])
def test_decomposed_request(self):
original = "caf\u00e9.txt"
self.assertEqual(find_name([original], "cafe\u0301.txt"), original)
def test_case_stays_distinct(self):
self.assertIsNone(find_name(["Report.txt"], "report.txt"))
def test_compatibility_stays_distinct(self):
self.assertIsNone(find_name(["\uff21.txt"], "A.txt"))
def test_collision(self):
names = ["caf\u00e9.txt", "cafe\u0301.txt"]
with self.assertRaisesRegex(ValueError, "ambiguous"):
find_name(names, "caf\u00e9.txt")
if __name__ == "__main__":
unittest.main()
Run python3 -m unittest -v. The baseline passes four tests and fails three: both cross-form lookups and the collision check. The collision test deliberately includes an exact match. Under this lab’s rule, an exact match does not override the presence of another canonically equivalent name.
Tell Claude what counts as the same name
Start claude in the practice folder, verify its working directory and review its active permissions. Paste:
Read matcher.py and test_matcher.py. Run python3 -m unittest -v.
Explain the failing cases using code points, not just rendered text.
Repair only matcher.py under this contract:
- Inputs are filename strings, not paths to access.
- Compare names and the request using NFC canonical normalization.
- Return the original inventory string for exactly one match.
- Return None for no match.
- Raise ValueError containing "ambiguous" for multiple matches,
even if one is an exact spelling match.
- Preserve case, compatibility distinctions and the input list.
Do not rename files, change tests, install packages, access external
services, commit or delegate. Run the same tests after the edit.
Report the actual test results and explain how collisions are handled.
If you cannot execute the tests, say so.
Anthropic’s debugging workflow recommends providing reproduction steps and the command that exposes the failure. Here, the unchanged tests also prevent an easy-looking repair from quietly broadening the matching policy.
The prompt defines the job; it is not a security boundary. Review tool requests against the practice-folder scope.
Review the repair before trusting the green result
A reference implementation is:
from unicodedata import normalize
def find_name(names, requested):
key = normalize("NFC", requested)
matches = [name for name in names if normalize("NFC", name) == key]
if len(matches) > 1:
raise ValueError("ambiguous filename")
return matches[0] if matches else None
Python documents normalize and its four forms. NFC uses canonical decomposition followed by composition. Applying it to both sides gives these canonically equivalent spellings the same comparison key. The returned value remains the inventory’s original string.
Exit Claude, inspect matcher.py and rerun python3 -m unittest -v yourself. The reference above passed all seven tests locally with exit status 0. That is evidence for this function on these fixtures, not a promise about what another agent session will produce.
I would keep the list of matches even if a dictionary looks tidier. A dictionary keyed by normalized names can overwrite an earlier entry before you notice there were two candidates. This task needs to report ambiguity, not hide it.
Reject fixes that change the policy
Using NFKC would also fold compatibility characters: the fullwidth A in the sixth test would match ASCII A. Unicode’s normalization specification distinguishes canonical equivalence from compatibility equivalence. Neither choice is universally correct; this exercise explicitly preserves compatibility distinctions.
Likewise, adding .lower() or .casefold() changes the case-sensitive contract. Removing accents would change it again. NFC does not mean “make everything that looks similar equal,” and this matcher is not a lookalike-character security detector.
If tests fail after the edit, read the failing case before asking for another rewrite:
- A cross-form lookup failure suggests only one side was normalized, or neither was.
- A compatibility failure suggests the implementation used NFKC or NFKD.
- A collision failure suggests it returned early or stored candidates in a structure that lost duplicates.
- An import error for
matchermeans you should check the current folder and the filename before editing the logic.
Real filesystems and applications have their own name-handling rules. This lab intentionally compares strings from an inventory; it does not prove that two physical files with these names can coexist on your machine. Before using a matcher in an importer, specify the source’s naming rules, retain original identifiers and decide how a person will resolve ambiguous records. Keep renaming as a separate, explicitly reviewed operation.
Sources
Checked November 17, 2026:
- Python: Unicode HOWTO — strings, code points and comparisons.
- Python: unicodedata — NFC, NFD, NFKC and NFKD normalization.
- Unicode: Standard Annex #15 — canonical and compatibility equivalence.
- Anthropic: Common workflows — reproducible debugging and test workflows.
Put this to work
How canonical Unicode equivalence differs from case folding and visual similarity.
Try
Repair a small Python filename matcher in a disposable folder.
Prove it worked
Run seven local checks for matching, nonmatching and ambiguous inputs.
Keep in view
- Reproduce a filename mismatch using explicit Unicode escapes.
- Ask Claude Code to change one matcher while preserving original names.
- Reject ambiguous matches instead of silently choosing a file.