Product case study · November 16, 2026
Ask Claude Code to fix a query string that changes your data
Repair a Python query builder with Claude Code, then check plus signs, ampersands, blank values and repeated filters with runnable local tests.

Define the decoded values first, then check that the query builder preserves them. A plausible-looking URL is weak evidence.
A search link can look readable and still ask for the wrong thing. Join q=C++ by hand, then decode it as form-style query data: the two plus signs become spaces. Add an ampersand to a value and you can accidentally create another field.
This is a useful small job for Claude Code because the result is easy to challenge. You do not need a live website or an API account. You need to show what went into the builder and what came back out.
Use Bash on macOS, Linux or WSL, Python 3, and an installed, signed-in Claude Code. All data below is fictional practice input. The Python baseline and reference repair were checked locally; the Claude prompt is an authored walkthrough, not a recorded agent run. Official sources were checked November 16, 2026.
Reproduce the changed search term
Create a practice folder and save a deliberately incomplete builder:
query_lab=$(mktemp -d /tmp/claude-query-lab.XXXXXX)
cd "$query_lab"
cat > query_builder.py <<'PY'
def build_query(pairs):
return "&".join(f"{key}={value}" for key, value in pairs)
PY
python3 - <<'PY'
from urllib.parse import parse_qsl
from query_builder import build_query
query = build_query([("q", "C++")])
print(repr(query))
print(parse_qsl(query))
PY
The baseline prints 'q=C++', then [('q', 'C ')]. The second line contains two spaces after the C. Nothing went over the network; the mismatch happened entirely inside the local example.
RFC 3986, section 2.2 explains why reserved delimiters need care when they represent data. This exercise specifically uses form-style query encoding. Do not generalize its plus-as-space behavior to every part of every URL.
Tell the agent what must survive
Save this contract beside the Python file:
cat > SPEC.md <<'SPEC'
build_query accepts an ordered list of (key, value) pairs.
Keys and values are raw Python strings, not pre-encoded fragments.
Return only a form-style query string, without a leading question mark.
Preserve pair order, repeated keys, empty values and Unicode text.
Encode both keys and values. Spaces use +; literal plus signs use %2B.
An empty list returns an empty string.
Use Python's standard library. Do not make network requests.
Do not add URL assembly, input coercion, sorting or deduplication.
SPEC
The input is a list because repeated filters are part of the requirement. Turning [('tag', 'python'), ('tag', 'agents')] into a dictionary would lose one entry before encoding even started. Whether a real server accepts repeated filters is a separate API contract; here we are testing the serializer only.
Save the following as test_query_builder.py:
import unittest
from urllib.parse import parse_qsl
from query_builder import build_query
CASES = [
([("q", "C++")], "q=C%2B%2B"),
([("q", "tea & cake=good")], "q=tea+%26+cake%3Dgood"),
([("tag", "python"), ("tag", "agents")],
"tag=python&tag=agents"),
([("q", "")], "q="),
([("a&b", "café/100%")], "a%26b=caf%C3%A9%2F100%25"),
([], ""),
]
class QueryTests(unittest.TestCase):
def test_encoding_and_round_trip(self):
for pairs, expected in CASES:
with self.subTest(pairs=pairs):
query = build_query(pairs)
self.assertEqual(query, expected)
self.assertEqual(
parse_qsl(query, keep_blank_values=True), pairs
)
Run:
python3 -m unittest -v test_query_builder
There is one test method with six subcases. The original builder fails three: literal plus signs, punctuation within a value, and the case with an encoded key and Unicode value. The repeated-key, blank-value and empty-input cases already pass. Keep those passing cases: they catch repairs that introduce a new regression.
Python’s unittest documentation describes subTest for distinguishing iterations within a test. Here the fixed expected strings check the wire representation, while decoding checks the data we wanted to preserve.
Ask Claude Code for a bounded repair
Start claude in the practice folder and paste:
Read SPEC.md, query_builder.py and test_query_builder.py.
Run python3 -m unittest -v test_query_builder and report the baseline.
Explain why joining raw strings changes some decoded values.
Change only query_builder.py to meet SPEC.md.
Keep the tests and contract unchanged. Do not install dependencies,
make network requests, commit changes or delegate work.
Run the same test command again and report the actual result.
Explain how your repair preserves repeated keys and blank values.
If you cannot run a command, say so instead of claiming it passed.
This follows Anthropic’s documented debugging workflow: supply a reproducible failure and verify the proposed fix. Check the session’s working directory and tool permissions before accepting commands. The prompt describes the intended scope; it is not a filesystem sandbox.
Review the small reference repair
A reference implementation is:
from urllib.parse import urlencode
def build_query(pairs):
return urlencode(pairs)
Python documents that urlencode accepts a sequence of pairs and preserves their order. Its default quoting handles form-style spaces and reserved characters. parse_qsl returns pairs; keep_blank_values=True keeps the empty value in our test.
Exit Claude, inspect the file and run the test command yourself. In the local reference check, all six subcases passed after this change. That result verifies the supplied implementation against these examples; it does not predict what a particular Claude session will produce.
Watch for three tempting repairs:
- Replacing only spaces: this leaves literal plus signs, ampersands and percent signs untreated.
- Converting pairs to a dictionary: this drops repeated keys.
- Encoding the whole assembled query: this also encodes the separators that should divide the fields.
If a test import fails, run from the folder containing both Python files. If only blank values disappear during decoding, check that the verification command includes keep_blank_values=True. If Claude edits a test expectation to match its output, restore the contract and ask for a repair to the builder instead.
Know what the passing result means
The function expects raw strings. Feeding it an already encoded value such as C%2B%2B correctly encodes the percent signs again under this contract; it does not recover the original C++ term. Choose one encoding boundary and pass raw values to it.
The exercise does not assemble full URLs, validate destinations, sign requests or establish how a remote service interprets repeated parameters. Those need their own requirements and checks. Before adapting this to an API client, read that API’s query-parameter rules and use a harmless request to verify the server’s interpretation.
The transferable agent habit is simple: specify the data that must survive, keep a failing example, and rerun the same checks after the edit. A readable link is a useful preview. A checked round trip is stronger evidence.
Sources
Checked November 16, 2026:
- Python: URL parsing and quoting — pair encoding, default quoting and blank-value parsing.
- Python: unittest — command-line execution and subtests.
- RFC 3986, section 2.2 — reserved characters as delimiters or data.
- Anthropic: Common workflows — reproducing bugs and checking fixes with tests.
Put this to work
How to turn a data-preservation requirement into a small coding-agent task.
Try
Repair a Python query builder in a disposable practice folder.
Prove it worked
Run the same six cases before and after the repair.
Keep in view
- Reproduce a search term changing when a query string is decoded.
- Give Claude Code fixed checks for punctuation, blanks and repeated filters.
- Review a standard-library repair without making a network request.