●CC 2.1.327 — Claude Code 2.1.327 (11/18) adds claude mcp add-json, which reads a server's JSON from stdin●MCP.JSON — The same release stops project-scope mcp add and remove from wiping other keys in .mcp.json●SONNET 4.5 — Retires on the Claude API on 11/30, 11 days left. Sweep model IDs in code and saved settings in one pass●GATEWAY — Users report that behind a gateway, 1M-context models compact so late that each reply takes tens of seconds●NEON — Gemini 4 Neon went GA on 11/18. If you run it next to Claude Code, keep each tool's MCP config separate●NEW — Linked Billing 402 or 403? Find Whose Wallet Is Empty First●CC 2.1.327 — Claude Code 2.1.327 (11/18) adds claude mcp add-json, which reads a server's JSON from stdin●MCP.JSON — The same release stops project-scope mcp add and remove from wiping other keys in .mcp.json●SONNET 4.5 — Retires on the Claude API on 11/30, 11 days left. Sweep model IDs in code and saved settings in one pass●GATEWAY — Users report that behind a gateway, 1M-context models compact so late that each reply takes tens of seconds●NEON — Gemini 4 Neon went GA on 11/18. If you run it next to Claude Code, keep each tool's MCP config separate●NEW — Linked Billing 402 or 403? Find Whose Wallet Is Empty First
My Porting Checklist Was Written in SwiftUI Terms, and It Couldn't Find a Single Purchase Item in My Objective-C Code
I built a small pipeline that hands Claude Code only the checks relevant to the file I'm editing, out of a 113KB list of 33 Android pitfalls. Three scripts, and how a SwiftUI vs Objective-C vocabulary gap let the most important items slip through.
In early November I was in the middle of moving features from the Android version of my wallpaper app over to the iPhone version. Next to me was a document I had been growing since spring: a list of pitfalls I had stepped on during Android device testing and post-release monitoring, written so that the iOS side would not repeat them. It had reached 33 items and 113KB.
That is far too much to hand Claude Code every time I open a file. So I put together a small pipeline that pulls out only the items relevant to the file being edited. When I tried it on the in-app purchase file, though, not a single purchase-related item came back.
The reason was almost embarrassing. The "iOS check" sections of my document were written in the vocabulary of SwiftUI and StoreKit 2, while the actual iPhone app is written in Objective-C. Both the document and the code are mine, and yet they were speaking different languages. I only noticed because the output was empty.
The short version
What I most want to pass on is this: an item your index fails to find is often not irrelevant. It may simply be written in different words.
Here is what I ended up with: three scripts and one command for calling them from Claude Code.
A structure check (duplicate numbers, ordering, missing or split sections)
An index that keeps only the "iOS check" section of each item
A lookup that matches identifiers in the file you are editing against that index, with a vocabulary bridge and a filter for common words
These are the results from running it against my real document and my real source tree. A lower hit count is not automatically better; what matters is whether the purchase items show up for the purchase file.
Stage
Result
Structure check
34 items (33 plus one sub-numbered item), 4 problems
Index, first version (bullet lines only)
8 of 34 items came out empty
Index, fixed version (prose and code included)
0 empty items, 113,432 bytes down to 42,884 bytes
Lookup on the purchase file (plain matching)
4 items, all matched on generic words like view controller references; 0 purchase items
An item you cannot find may not be irrelevant; it may just be written in different words. That one sentence is the line I drew from this work.
What the document looks like, and which part Claude Code needs
Every item in the pitfalls list has four sections:
Symptom: what happened
Cause: why it happened, structurally
Android fix: how I fixed it
iOS check: what to verify on the iOS side so the same thing doesn't happen again
While I'm porting, what Claude Code actually needs is almost always the last one. The symptom and cause are background for my own judgment, and the Android fix is Java, which doesn't transfer to the iPhone code as-is. So I settled on two layers: an index of the check sections, keyed by item number, and the full document for the occasional item where the backstory matters.
The catch is that if the document's shape isn't consistent, items quietly fall out during extraction. I had been adding to this file for months, and its shape had drifted more than I realized.
✦
Thank you for reading this far.
Continue Reading
What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.
WHAT YOU'LL LEARN
✦You will be able to catch, before a port begins, the case where your checklist and your codebase speak different languages and the most important checks silently never match
✦You can now hand Claude Code only the checks that matter for the file you are editing, instead of making it read a 33-item, 113KB pitfalls document every time
✦You will be able to detect drifting section names and numbering mechanically, before your index quietly drops items
Secure payment via Stripe · Cancel anytime
✦
Unlock This Article
Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.
The first script only counts. It reads each numbered heading and checks which sections exist under it. My headings use keycap digits like 1️⃣2️⃣, so the script converts those back to integers.
#!/usr/bin/env python3"""移植用つまずき集の構造を検査する(番号の重複・順序・4欄の欠け)。"""import sysfrom pathlib import PathKEYCAP = "️⃣" # 1️⃣ = "1" + VS16 + 囲み記号REQUIRED = { # 欄の別名をまとめて1つの役割として数える "symptom": ("症状",), "cause": ("原因",), "fix": ("Android 修正", "Android 対応", "運用修正", "Android 採用方針"), "check": ("iOS チェック", "iOS 監視ポイント"),}def parse_number(heading: str): """'## 1️⃣2️⃣b ...' → (12, 'b')。番号のない見出しは None。""" body = heading[3:] if body.startswith("🔟"): return 10, "" digits = "" while body[:3] and body[1:3] == KEYCAP: digits += body[0] body = body[3:] if not digits: return None suffix = body[0] if body[:1].isalpha() and body[:1].isascii() else "" return int(digits), suffixdef split_items(text: str): items, cur = [], None for line in text.splitlines(): if line.startswith("## "): num = parse_number(line) cur = {"num": num, "title": line[3:].strip(), "subs": []} if num else None if cur: items.append(cur) elif cur and line.startswith("### "): cur["subs"].append(line[4:].strip()) return itemsdef lint(path: Path) -> int: items = split_items(path.read_text(encoding="utf-8")) problems, seen, prev = [], {}, 0 for it in items: n, sfx = it["num"] key = f"{n}{sfx}" if key in seen: problems.append(f"#{key} 番号が重複: {it['title'][:40]}") seen[key] = it["title"] if n < prev: problems.append(f"#{key} が #{prev} の後ろにある(並び順)") prev = max(prev, n) for role, names in REQUIRED.items(): count = sum(1 for s in it["subs"] if s.startswith(names)) if count == 0: problems.append(f"#{key} に {role} 欄がない") elif count > 1: problems.append(f"#{key} の {role} 欄が {count} つに分かれている") print(f"items={len(items)} problems={len(problems)}") for p in problems: print(" " + p) return 1 if problems else 0if __name__ == "__main__": sys.exit(lint(Path(sys.argv[1])))
(The messages are in Japanese because the document is; they read "the check section is split in two", "#23 sits after #24", and so on.)
Two things surprised me.
First, the "fix" section had quietly grown four different names. Items fixed through operations rather than code were labeled "operational fix", items where I had only decided on a policy were labeled "adopted approach", and an item still under investigation had "Android response". Before I grouped those aliases in REQUIRED, three items were reported as having no fix section at all. To me they were natural rewordings. To a script they were different sections.
Second, items that I had updated with follow-up notes, like #29, ended up with the same section twice. An extractor that only picks up the first one would silently drop the newer check. The ordering warning for #23 and #24 is intentional: the document notes that #24 should be read after #23 chronologically, so I left it and kept the warning. And #25b exists because I once gave the number #26 to two different items and renumbered one of them later; the duplicate check is there so that doesn't happen again.
Build an index of only the check sections
The second script pulls out the "iOS check" section of each item and writes the number, title, check lines, and search keys to JSON.
My first version only collected bullet lines from the check section. Eight of the 34 items came out empty. Reading them again, those eight had their checks written as plain prose, or as a Swift code sample placed directly under the heading. The assumption that checks would always be bullet points was mine, not the document's.
The fixed version keeps prose lines too. For code, it adds type and method names to the search keys and keeps only the first few lines.
#!/usr/bin/env python3"""つまずき集から「移す側の確認」欄だけを抜き、番号つきの小さな索引にする。"""import jsonimport reimport sysfrom pathlib import Pathfrom lint_pitfalls import parse_numberCHECK_HEADS = ("iOS チェック", "iOS 監視ポイント")CODE_TOKEN = re.compile(r"`([^`]{3,60})`") # 本文中のバッククォート語を検索キーに使うIDENT = re.compile(r"\b(?:[A-Z][a-z]+[A-Z]\w+|[a-z]+[A-Z]\w+)\b") # コード中の型名・メソッド名CODE_KEEP = 6FENCE = "`" * 3 # 記事や文書の中で囲みが閉じないよう、文字を並べて作るdef build(src: Path) -> list[dict]: entries, cur, in_check, in_code, code_lines = [], None, False, False, 0 for line in src.read_text(encoding="utf-8").splitlines(): if line.startswith("## "): num = parse_number(line) cur = None if num: n, sfx = num cur = {"id": f"{n}{sfx}", "title": re.sub(r"^\S+\s*", "", line[3:]).strip(), "checks": [], "keys": set()} entries.append(cur) in_check = in_code = False continue if cur is None: continue if line.startswith("### ") and not in_code: in_check = line[4:].startswith(CHECK_HEADS) continue if not in_check: continue stripped = line.strip() if stripped.startswith(FENCE): in_code, code_lines = not in_code, 0 cur["checks"].append(stripped) continue if in_code: cur["keys"].update(k.lower() for k in IDENT.findall(line)) code_lines += 1 if code_lines <= CODE_KEEP: # 長いコードは先頭だけ残す cur["checks"].append(line.rstrip()) continue if stripped and stripped != "---": # 箇条書きでない地の文も「確認」に含まれる cur["checks"].append(stripped) cur["keys"].update(t.lower() for t in CODE_TOKEN.findall(line)) for e in entries: e["keys"] = sorted(e["keys"]) return entriesif __name__ == "__main__": src, out = Path(sys.argv[1]), Path(sys.argv[2]) data = build(src) out.write_text(json.dumps(data, ensure_ascii=False, indent=1), encoding="utf-8") empty = [e["id"] for e in data if not e["checks"]] print(f"items={len(data)} src={src.stat().st_size}B index={out.stat().st_size}B empty={empty}")
The result was items=34 src=113432B index=42884B empty=[]. No empty items, and the index is about 38% of the original size.
The reason the structure check runs first is that this script decides where a check section begins and ends by its heading name. If those names drift, the index doesn't complain; it just leaves the item empty. Running the check first means that when an empty item does show up, I already know whether it's a document problem or an extraction problem.
Look up the checks that matter for the file you are editing
The third script is the point of all this. It collects identifiers from the file you are about to edit, matches them against the index keys, and prints only the items that look relevant.
I started with plain matching, and that produced the empty purchase result I mentioned at the top. The four items it did return for the purchase file all matched on words like UIViewController or viewController, which appear everywhere. For the large main screen file it returned 15 of the 34 items, which is barely a filter at all.
So I added two things.
One is dropping words that appear across most of the project. I counted the 44 source files of the iPhone app and treated any word appearing in more than 20% of them as common. That removed the generic matches, and the purchase file's result went to zero. The noise was gone, and the real problem was now plainly visible.
The other is the vocabulary bridge. The pitfalls document says Transaction.currentEntitlements and scenePhase. My purchase code uses SKPaymentQueue and restoreCompletedTransactions, and it hears about returning to the foreground through sceneDidBecomeActive. I wrote that mapping down as a small table and consult it during matching.
#!/usr/bin/env python3"""編集するファイルの識別子から、該当しそうな「移す側の確認」だけを引く。"""import jsonimport reimport sysfrom pathlib import PathPINNED = ("1", "12") # 語彙では引けないが毎回読む項目(つまずき集で「最重要」の2件)WORD = re.compile(r"[A-Za-z_][A-Za-z0-9_]{3,}")# チェック欄は SwiftUI の語彙で書かれている。手元が Objective-C なら、ここで語彙をつなぐ。ALIASES = { "scenephase": ["sceneDidBecomeActive", "applicationDidBecomeActive", "sceneWillEnterForeground"], "transaction.currententitlements": ["SKPaymentQueue", "restoreCompletedTransactions", "paymentQueueRestoreCompletedTransactionsFinished"], "transaction.updates": ["addTransactionObserver", "updatedTransactions"], "@mainactor": ["dispatch_get_main_queue", "isMainThread", "performSelectorOnMainThread"], "dispatchqueue.main.async": ["dispatch_get_main_queue"], "uipageviewcontroller.setviewcontrollers(...)": ["setViewControllers"], "traitcollectiondidchange": ["traitCollectionDidChange", "hasDifferentColorAppearanceComparedToTraitCollection"], "removeall": ["removeAllObjects"],}def file_words(path: Path) -> set[str]: return {w.lower() for w in WORD.findall(path.read_text(encoding="utf-8", errors="ignore"))}def common_words(corpus: Path, ratio: float) -> set[str]: """プロジェクトの多くのファイルに出る語(viewController など)は手がかりにならない。""" files = [f for f in corpus.rglob("*") if f.suffix in (".m", ".swift") and "_backup" not in f.parts] df: dict[str, int] = {} for f in files: for w in file_words(f): df[w] = df.get(w, 0) + 1 return {w for w, n in df.items() if n / max(len(files), 1) > ratio}def match(index, words, use_alias, common=frozenset()): hits = [] for e in index: why = [] for key in e["keys"]: parts = [p.lower() for p in WORD.findall(key)] # 'gadappopenad.present(...)' → 語に分ける if parts and all(p in common for p in parts): continue # ありふれた語だけのキーは捨てる if parts and all(p in words for p in parts): why.append(key) elif use_alias: for alias in ALIASES.get(key, []): if alias.lower() in words and alias.lower() not in common: why.append(f"{key}≈{alias}") if why: hits.append((e["id"], why)) return hitsif __name__ == "__main__": index = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8")) use_alias = "--no-alias" not in sys.argv args = [a for a in sys.argv[2:] if not a.startswith("--")] corpus = next((a.split("=", 1)[1] for a in sys.argv if a.startswith("--corpus=")), None) common = common_words(Path(corpus), 0.2) if corpus else set() for target in args: hits = match(index, file_words(Path(target)), use_alias, common) ids = [i for i, _ in hits] print(f"{Path(target).name}: {len(hits)} items", " ".join(f"#{i}" for i in ids)) by_id = {e["id"]: e for e in index} for i in list(PINNED) + [i for i in ids if i not in PINNED]: why = dict(hits).get(i, ["pinned"]) print(f"\n#{i} {by_id[i]['title'][:50]} ({', '.join(why[:2])})") for line in by_id[i]["checks"][:5]: print(" " + line)
With the bridge in place, the purchase file returned five items: #2 (the ad-free state briefly flickering back to unpaid), #5 (cancellation being handled twice), #10 (purchase calls made off the main thread), #15 (a rewarded-ad manager holding on to a stale screen, whose check also covers main-thread handling), and #31 (tearing down the purchase client on the main thread). Every one of them is something I want to read before touching purchase code.
Across eight of the main files, total hits went from 58 to 33. The main screen file dropped from 15 to 9 and the theme manager from 5 to 2. What disappeared were generic matches on screen references; what appeared were purchase and foreground-return items found through the bridge.
Pin the two items that matter most
Even then, one item would not come up: #1, which the document marks as the most important. It is about ads not coming back after a subscription expires.
Its check section is written in terms of timing: re-evaluate the purchase state whenever the app becomes active again. It barely mentions any purchase API names, so there is nothing in the purchase file for it to match. No matter how much the bridge table grows, lookup by vocabulary has a ceiling.
So #1 and #12 (a static holder keeping a reference to a screen that is already gone) are printed first every time, whatever the lookup finds. That is PINNED in the code above. The machine proposes candidates; I decide by number which items are always read. Since splitting the work that way, I've had one less thing to worry about when reading the output.
Calling it from Claude Code
Finally, the custom command. You place a Markdown file under .claude/commands/, and the !-prefixed line injects the lookup result into the prompt. I ran the three scripts against my real document and source tree and checked their output. This command, however, is something I've written to match the custom command format in the official documentation and have only just set up, so please adjust the paths to your own project.
---description: Before editing, read only the relevant checks from the porting pitfalls listargument-hint: <file to edit>allowed-tools: Bash(python3:*)---## Checks that look relevant (from the index)!`python3 tools/pitfalls/lookup_checks.py tools/pitfalls/checks.json $ARGUMENTS --corpus=App/Classes`For each item above, answer in one line whether the change to $ARGUMENTS is affected.For items that don't apply, write only "not applicable".Open the numbered section of docs/ios-pitfalls-from-android-ja.md only for items where you need the full story.
For the purchase file, what gets injected is about 3.6KB. Compared with reading a 113KB document every time, far less piles up in the context on each task. I treat the index as something regenerated from the document, never edited by hand. When I add to the pitfalls list, I follow three steps:
Run the structure check and confirm there are zero problems, or only warnings I chose to keep
Rebuild the index and confirm zero empty items
Try the lookup on the purchase file and a screen file, and see whether the items that come back changed much since last time
I never skip straight to rebuilding the index. Section names drift most on the day I add something.
Collecting only bullet lines makes checks disappear without a word. My first version left 8 of 34 items empty. Print the count of empty items every run, and stop if it isn't zero.
Where "common" begins depends on the size of the project. I used 20% across 44 files. With fewer files each one weighs more, so whenever I change the threshold I compare results on at least the purchase file and a screen file before adopting it.
Cutting code samples to six lines can drop the one line that matters. Always print the item number with the index output, and keep the escape hatch of opening the full section by number.
A session working on something else can overwrite your document from a stale copy. This actually happened to my porting plan: it was saved again from an old copy and the iOS implementation notes vanished. I restored them and added a line at the top of the plan: re-read the current file before writing. It is also part of why the index is always rebuilt from the canonical document.
What to try next
If you have a pitfalls list or porting notes of your own, try running just the first structure check against them. Simply counting how many names a single section has drifted into gives you a good sense of what an index would silently drop.
As an indie developer growing the same app on both Android and iPhone, I expect my documents and my code to drift into different languages again. When a lookup comes back empty, I'd rather pause and ask whether it's only the words that differ before deciding the item doesn't apply. I keep to that order every time I port something.
Share
Thank You for Reading
Claude Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.