DEV Community: Takashi Abe

PunyGuard: A Chrome Extension That Blocks Every Internationalized Domain

Takashi Abe — Fri, 16 Oct 2026 09:02:56 +0000

аррӏө.com and apple.com. Put them side by side: can you tell which one is real?

All five letters in the first one are Cyrillic. Even so, Chrome 154's address bar displayed it exactly as-is. It looks identical to apple.com (GIZMODO article).

After reading that article, I built a small Chrome extension called PunyGuard. It blocks access to internationalized domain names (IDNs), all of them, no exceptions. It doesn't judge whether a domain looks similar to anything. Legitimate Japanese domains get blocked too. It may look like a heavy-handed tradeoff, but that tradeoff is the core of the design.

Out of nowhere, a confession: I don't like Japanese domain names. Rather than getting sent to some Japanese-named site where I can't even tell who's behind it, I'd honestly prefer not to be able to reach it at all. That conviction is what the whole design rests on.

So instead of making the machine do fuzzy judgment calls, I gave it a rule it can't get wrong. The machine handles the routine work; I decide what to protect and what to give up. It's a small extension, but the way I think about working with computers and AI shows up directly in both its design decisions and how I built it.

https://github.com/sho7650/punyguard

ℹ️ If you use unbound (I do too), riorist's post Preventing homograph attacks with Unbound (in Japanese) is worth a look too. Since it works regardless of which browser you use, it's arguably the more secure option.

Miss one character, and the look-alike detection falls apart

Chrome has a mechanism that displays domains containing confusable characters in Punycode. Punycode is a scheme for rewriting domain names that contain non-ASCII characters (ASCII being half-width letters, digits, and symbols), like Japanese or Cyrillic, into an ASCII string starting with xn--. аррӏө.com becomes xn--80a6aa68c8d.com. If a suspicious domain is shown as that jumble of symbols, at least it won't look like apple.com.

So what counts as "confusable"? The basis for that call is a list of look-alike characters. This time, ө (U+04E9) wasn't on the list. Because of that single missing character, five Cyrillic letters sat in the address bar looking exactly like the real thing.

I don't think this is really anyone's mistake so much as a limit of the approach itself. The world has an enormous number of characters, and how they look changes from font to font. Exhaustively listing every "similar-looking character" is a job that never ends. However carefully you grow the list, the next ө will be hiding somewhere.

Human eyes are the same. The assumption that you can tell them apart if you look carefully collapses instantly in the face of a one-character difference. So I decided to stop judging by appearance altogether.

A design that stops judging

All PunyGuard looks at is whether the hostname has a label starting with xn--. That's it. A label is each piece of www.example.com split by .. If even one label starts with xn--, the host is treated as an IDN host and blocked.

However natural an internationalized domain looks on screen in the browser, on the wire it always carries the xn-- prefix. A gatekeeper who judges by faces is vulnerable to look-alikes. A gatekeeper who checks name tags doesn't hesitate, no matter how similar the faces are. I built PunyGuard to be the second kind of gatekeeper.

Before settling on this policy, I considered other paths and left a decision record (ADR). One option was to draw the line by script: let kanji and kana through, block Cyrillic and so on. Its upside is that Japanese domains would get through. But even within the allowed scripts there are confusable characters, so it just moves the problem somewhere else. Another option was to judge by visual similarity, which is the same idea Chrome uses, and exactly the approach that let this one slip through. And as I said, I dislike Japanese domains.

What I agonized over most was an allowlist and a "proceed just this once" button. They'd be convenient. But as long as the warning screen has a button to proceed, there's room for someone to sweet-talk you into pressing it. Phishing is, after all, also the art of getting people to press buttons. I decided to leave them out of v1, and recorded them in the ADR as candidates to add if they ever become truly necessary.

The price I pay instead is clear. Legitimate Japanese domains like 日本語.jp get blocked too. Since I dislike Japanese domains myself, I judged that these false positives don't hurt me. For people who use Japanese domains, it's an inconvenient extension, and I said so near the top of the README. This is a tool for me, first and foremost. It's enough if the people who share my philosophy get it.

Just one blocking rule

The core of the implementation is Chrome's declarativeNetRequest (DNR from here on). An extension registers rules with Chrome along the lines of "treat requests matching this condition like this," and from then on Chrome applies them itself. The extension doesn't need to peek at every page the user visits.

PunyGuard registers just one rule, and its condition is this regex:

^https?://(?:[^/?#]*[.@])?xn--

Reading from the start of the URL, it matches if any label in the hostname starts with xn--. It also blocks when the top-level domain is an IDN (e.g. example.xn--q9jyb4c). It doesn't match hosts that merely have xn-- in the middle of a label (axn--b.com), or xn-- appearing in the path or query. It applies to two things, top-level page navigations and pages embedded in another page (iframes), and doesn't affect loading of resources like images or scripts.

DNR converts the hostname to Punycode before matching. So even if you type аррӏө.com into the address bar in Unicode, the same rule catches it. Clicking a link, typing in the address bar, a server-side redirect, a link opened from another app: whatever the path, the result is the same.

The requirement I first wrote down was "if a URL contains anything other than English ASCII, refuse the click." While working out the plan, I realized I couldn't build it as written, and revised it in two directions.

First, I narrowed the check to the hostname (FQDN) only. If paths were included, pages like ja.wikipedia.org/wiki/東京 would get blocked too, which would make it unusable. Besides, by the time a request goes out, Japanese in the path has already been converted into an alphanumeric sequence like %E6%9D%B1, so you can't even ask "does it contain non-ASCII?"

Second, I widened it to block paths other than clicks. Behind the wording of the requirement was the actual goal: "don't let me get to a fake site." Rather than building it to the letter, I chose to build it to that goal.

Why ask for one more permission?

After blocking, what do you show the user? This is where I made one big decision.

DNR has block, which simply stops the request, and redirect, which sends it somewhere else. With block, the permissions you request stay minimal. But what the user sees is Chrome's standard error screen, ERR_BLOCKED_BY_CLIENT. That gives no way to tell whether the network is acting up or an extension blocked it. Faced with an unexplained wall, some people would get confused and just remove the extension.

So I went with redirect, sending the user to a warning page bundled with the extension. The catch is that redirect requires access to all sites (<all_urls>). Minimal permissions versus telling the user why it was blocked: I weighed the two and chose the latter.

Access to all sites is on the larger end of extension permissions. That's exactly why I keep everything else doing as little as possible. There isn't a single program that touches the content of the page you're viewing (a content script). It makes no external requests and stores nothing. What it requests, what it doesn't do, and why are all written plainly in the README. An extension that can't explain why it needs such broad permissions deserves not to be trusted.

The redirect URL includes the extension's ID, and the ID varies by environment. So instead of hard-coding the rule in a file, the extension builds and registers it when it starts up. It re-registers every time: on install and update, and on browser startup. Dynamically registered rules are supposed to persist across restarts, but I decided not to rely on that "supposed to."

The warning page trusts nothing

The warning page shows the original URL, the hostname in both Unicode and Punycode, and a list of the non-ASCII characters. For аррӏө.com, you can see that ө is Cyrillic U+04E9. It's a screen that reveals, character by character, an identity you can't see by looking. The display language follows the browser: Japanese for Chrome in Japanese, English otherwise.

The original URL is passed in the fragment (the part after #) of the redirect URL. The thing I was careful about here was not trusting any input to this page at all. The warning page can be opened from anywhere on the web with any fragment attached. You have to build it assuming a malicious string will show up.

All output to the screen goes through textContent, so there's no path for a string to be interpreted as HTML. If a URL comes in that can't be parsed, it shows only generic text, with no host information. The original URL isn't turned into a link, and there's no button to copy it either. I decided from the start not to build anything you could press by accident.

On a smaller note, I tripped over the string :~:. Chrome strips the #:~:text= syntax, used to jump to a specific passage on a page, from the URL the page can read (location.hash). If the original URL happens to contain :~:, everything after it disappears. This was caught in a review by Codex, and I fixed it to read the URL from the navigation history, before the stripping happens.

There are two buttons. The primary one, "Close this tab," is always shown. It's the action that best fits the goal of getting away from a suspicious link. The secondary one, "Go back to the previous page," is shown only when there's history. When the warning page appears inside an iframe, neither is shown. Closing the parent page's tab from inside an iframe goes beyond what the user intended.

I thought about the buttons a lot. I wanted to get away with a single button, "go back if you can, close if you can't," but browsers have no way to accurately check whether there's cross-site history behind you. I also considered going back, waiting a bit, and closing the tab if the page was still there. But deciding based on a wait time risks closing the tab while it's still on its way back to a heavy page. Rather than break the tab with an inaccurate check, it's better to accept that there will be cases where it misses, and say so honestly. That's why I split it into two buttons.

I also planned for cases where scripts don't run. If the redirect lands in an iframe whose embedder has disabled scripts with the sandbox setting, the warning page's JavaScript won't run. So the HTML ships with a fixed warning message, in both Japanese and English, from the start. Even without the details, the one line "PunyGuard blocked navigation to this page" gets through.

One more thing: if the URL contains a password, as in https://user:password@..., it's removed both from the display and from the warning page's own address bar. Exposing a secret on screen as a result of blocking would defeat the purpose of a protective tool. That said, the other Shossan living in my head does feel like "you didn't have to go that far..."

The scariest defense is the one that fails silently

The thing I most want to avoid in a security tool is a state where it's broken and nobody notices. When it looks like it's working but actually isn't protecting anything. In developing PunyGuard, I spent a lot of time figuring out how to stamp out these "silent failures."

The first pitfall was regex dialects. DNR regexes aren't interpreted by JavaScript's regex engine but by a separate one called RE2. RE2 doesn't support some constructs, like lookahead, and Chrome also rejects regexes that are too large. Meanwhile, ordinary unit tests run on JavaScript regexes. Even if you use something RE2 can't handle, the tests pass. Ship it like that, and rule registration fails, and nothing gets blocked. And nothing at all happens on screen.

I considered testing with a package that lets you call RE2 from Node instead. But that package translates JavaScript-style syntax for RE2 before running it, so it even lets through syntax that Chrome would reject. No matter how much you check in a similar environment, you won't get the same answer as production.

What I ended up choosing was to have Chrome itself try it. In end-to-end tests (E2E tests) that actually drive a browser, I load the extension into a real Chromium. Then I pass the exact rule I'm going to register to Chrome's isRegexSupported and have it answer whether it can be used. In the end, only production knows the answer. So run it in production.

Even so, the chance of registration failing on a user's machine isn't zero. When that happens, a ! badge shows up on the toolbar icon.

There was one more easy-to-miss hole. On Chrome's extensions page, users can restrict site access to "On click" or to specific sites. When they do, rule registration still succeeds, but only the redirect stops working. No error shows up anywhere. So I added a check for access to all sites, and if it's missing, the same ! appears. You can see the cause in the tooltip that appears when you hover over the icon. To keep a stale check result from overwriting the badge when access is toggled quickly, the checks run one at a time, in order.

In a normal window, if there's no !, blocking is working. I wanted to make it unmistakable that the settings and state are correct.

Say what it can't do

PunyGuard has a few weaknesses I left in knowingly.

One is a known false positive. If xn-- appears in the username part of a URL, as in https://xn--a@example.com/, it gets blocked even though the host is plain ASCII. Fixing it properly would take a pretty complex regex within RE2's constraints. I've never seen anyone open a URL like this, and the only harm is the blocker being wrong, so for now it stays as specified behavior, and there's a test confirming it.

Another is the back button. If the warning page opens as the first page of a new tab, and you navigate elsewhere and then come back with the browser's back button, "Go back to the previous page" is shown, but pressing it does nothing. That's the price of "accepting cases where it misses" from earlier; even in this state, "Close this tab" works.

What I struggled with most was incognito windows. Chrome doesn't run extensions in incognito windows unless the user turns on "Allow in Incognito." If it isn't allowed, IDN hosts aren't blocked, and the badge doesn't warn you either. Showing ! forever to someone who has deliberately chosen not to allow it would be unkind.

Even when it is allowed, the bundled warning page can't be shown in incognito tabs. Navigation to IDN hosts is blocked, but the screen shows Chrome's ERR_BLOCKED_BY_CLIENT, and the address bar keeps the original URL, password and all. Switching the extension's operating mode might have made it possible to show the warning page. But that would mean reworking the foundation of the design, and all it would buy is the "show the reason" part, not the "block" part. Since blocking itself works, this time I only documented it in the README.

Hand repetitive work to machines

Once I actually built it, I spent more time on the machinery around PunyGuard than on PunyGuard itself.

The development environment is generated from copier-ts7, a template for TypeScript 7 that I made. The Node.js and pnpm versions are pinned with a tool called Nix, so the same versions run both on my machine and in CI, which runs automated tests on GitHub. A single pnpm run check runs, in order, type checking, linting, format checking, and tests that require at least 80% coverage.

Releases are handled by an automation tool called release-please. As long as commit messages follow a set format, every time a change lands on main, it automatically creates a PR with the next version and the changelog. Merging that PR creates a tag and a GitHub Release, and bumps the version in package.json and manifest.json. A workflow then builds the tagged commit and attaches punyguard-vX.Y.Z.zip to the Release. Handy. I always forget to bump version numbers, so most of the apps I publish manage their versions this way.

What the human doesn't hand over when building with AI

As has become my usual lately, I built PunyGuard together with Claude Code. Write a plan, write tests first, then implement, set up E2E tests, build the release pipeline. Most of the code writing and running was done by the AI. And for every PR, I had Codex review it. I've set up skills so all of this happens entirely within Claude Code.

This combination is very effective, and not just for this app. The :~: URL truncation, tests and the shipped build loading different files, the warning page not opening in incognito windows: all of these were first found in Codex reviews. Separating the writer from the reader makes it less likely that both fall into the same assumptions and the same unnecessary biases. The logic is the same as asking someone else to review your code on a human team.

On the other hand, there's one thing I didn't hand to the AI: making the decisions.

I'm the one who decided to block legitimate Japanese domains too. The AI's reaction was along the lines of "surely Japanese is fine...", but as I keep saying, I dislike Japanese domains. Narrowing the check to hostnames, and deciding to handle the incognito problem in the README only, were also all my calls. The AI lays out the options and the cost of each, carefully. But which cost to accept can only be decided by a human who knows the circumstances of the people using it. I can say the pain of false positives is small precisely because I'm someone who dislikes Japanese domains.

That's why I always write down what I decide. Decisions, their reasoning, and the options I considered and rejected go in ADRs. Definitions of terms go in a glossary (CONTEXT.md). The plan, progress, and deferred issues with their reasons go in the plan document (tasks/todo.md). When working with AI, conversation memory gets summarized mid-way or cut off across days. If I had to explain everything from scratch each time, the context wouldn't be enough, and neither would my patience. If it's written down, the AI can interpret it in the next session and start from the same premises. The same goes for me reading it back six months from now.

I also kept the final check as a human job. Links opened from external apps, switching Chrome's display language, the badge when site access is restricted, browser restarts, incognito windows. These are hard to verify with automated tests, so I checked each one myself in a real Chrome. You must not trust AI-written code on the strength of AI-written tests alone. Only after checking with my own eyes can I look anyone in the eye and say "it works."

AI lends you more hands and an extra pair of eyes. Deciding what to build, what to give up, and whether it really works is, for now, the human's role. Draw that line clearly, and you can hand work to AI with peace of mind.

I didn't choose the path of better detection

There was surely a path of making the detection smarter. Grow the list, refine the similarity calculation, keep adding exceptions. PunyGuard didn't take that path. I made one single decision, not to judge, and handed the job of upholding it to a machine that never gets tired.

Choose simplicity that never hesitates over competing on cleverness. That's the distance I want to keep when working with computers and AI.

I decided not to put PunyGuard on the Chrome Web Store. It's distributed only on GitHub. Grab punyguard-vX.Y.Z.zip from Releases, unzip it, turn on Developer mode at chrome://extensions, and load it, and it'll work. Please leave site access set to "On all sites." If you don't use Japanese domains and you're worried about phishing with look-alike domains, I'd be glad if you gave it a try.

Why not the Web Store? It's something I made for myself, and I just didn't want to start fielding "please make it do this!!" requests from other people. That said, if you share Shossan's philosophy, feel free to use it.

https://github.com/sho7650/punyguard

My Obsidian Vault Made 21 Permanent Notes in 3.5 Years, So I Redesigned It

Takashi Abe — Sun, 11 Oct 2026 03:50:09 +0000

What I use Obsidian for, and what went wrong

I adopted Obsidian to build knowledge for myself.

Take in lots of personal knowledge through all kinds of methods, and turn it, one by one, into Permanent Notes: finished pieces of my own wisdom
Build up those Permanent Notes and hand them down as a body of explicit knowledge for those who come after me

Above all, I believed Obsidian's job was to keep producing solid Permanent Notes out of the collective knowledge I'd gathered. Or so I thought.

But the Permanent Notes just weren't growing. At all. It was a disaster. Obsidian had been reduced to a plain old diary.

I'd also assumed, on my own, that the reason Permanent Notes weren't growing was that "the notes aren't connected to each other." But when I dug into the vault with Claude Code's help, the cause turned out to be somewhere else. What was missing was a step where I write down my own claims, and the time to actually do it every day.

21 notes in three and a half years, zero in the last 90 days

What I want from Obsidian is to keep producing solid Permanent Notes, one at a time, from the knowledge I collect. Each note is meant to be about the size of an index card, something my future self or people coming after me can reuse.

When I actually counted, here's what I found:

Aspect	Actual
Number of Permanent Notes	21 (over roughly three and a half years since February 2023)
Last Permanent Note update	August 2025. Zero in the last 90 days
Inflow over the last 90 days	79 Clippings, 142 AI conversations and summaries, 1 Fleeting Note, 6 Inbox

What comes in is other people's writing and AI's writing. There are almost none of my own insights in Obsidian. My Daily Note has a section called "Thoughts in my mind," but I've kept it empty the whole time. Meanwhile, the KPI section where I log sleep hours and running distance gets filled in every day. The sections measured in numbers stuck; the free-writing section didn't.

Adding links didn't grow my Permanent Notes

In March 2026, I built a Claude skill, /zettelkasten, that automatically adds tags and links to Fleeting Notes, and ran it on 99 of 281 notes. Each note also got a list of related notes appended at the end. That was seven months ago. Not a single note has been promoted since.

The reason was obvious the moment I opened the Fleeting Notes. Most of them are just a title. Terrible. One note I wrote in February 2024, "Transcribing from memos is what really matters, so set up a time to transcribe," had an empty body too. I'd written down the answer myself two years earlier, then left it there without ever making time to transcribe. Truly terrible.

The notes that did have a body had problems too. "Architecture is just one hypothesis" still contained an AI reply, "Thank you for your understanding," verbatim. Worse and worse. Before I could even connect anything, the things I'd be connecting weren't in my own words.

The bar of "unshakable intelligence" was what kept me from writing

I had selfishly defined a Permanent Note as "definitive, unshakable intelligence." With that bar, the day I could call a note finished was never going to come.

My existing 適応度関数.md (fitness function) note was a textbook example. The title says "fitness" (適応度), yet the body says "goodness of fit" (適合度) nine times, for some mysterious reason. The title and the content don't even fit each other. It cited no sources, and the second half just restated the first. I hadn't touched it since May 2024. The note that was supposed to be unshakable had, in reality, become a note nobody revisits, or even looks at.

So I lowered the bar to "correct as of the verification date, and revisable later," and set six criteria:

The title is a single-sentence claim
The body is in my own words and covers the claim, the reasoning, a concrete example, and the scope (around 200–400 Japanese characters)
There's at least one piece of supporting evidence
The verification result and the verification date are recorded
The note makes sense when read on its own
Its visibility (visibility) is set

I added the last one to check whether the content trips any confidentiality concerns: words meant only for me should be explicitly marked as never to be seen by anyone else. If you're going to let arbitrary readers see your notes, you need to decide, note by note, whether each one is okay to publish.

I write the claims; AI handles verification

I chose who writes the body from three options. Letting AI write it and just approving would be the fastest and produce the most notes. But that's the same as building one more "storehouse of AI-written text," just like what I already had. I chose the option where I write the claims and reasoning myself. Obviously. Claude Code can't be expected to understand what's obvious to me, but I think I should be grateful that it catches the biases humans like me let slip by.

Since these are my claims and my own knowledge in the first place, I narrowed the AI's role down to the minimum:

Check factual statements against primary sources
Present the strongest counterargument to the claim
Suggest related notes

I don't let the AI rewrite the body. It only points out what to fix; I'm the one who rewrites. With this setup, about 100 notes a year is the ceiling, but only knowledge I can explain myself gets properly kept.

Keep the writing entirely inside Obsidian

The first system that came out of this was one Claude Code proposed to suit itself: a flow driven by conversation with Claude Code. It asks me questions, I answer, and I get verification results on the spot. It's comfortable enough when you use it, but you can't run it from inside Obsidian. That didn't match my premise: right after reviewing my Daily Note, spend 15 minutes writing, right there in Obsidian.

Breaking the process into steps, the only part of this flow that actually needs AI is verification. The questions are the same every time, so I realized I could just put them in a template. So I moved the writing into Obsidian and turned verification into a batch job that runs in the background.

My daily flow looks like this:

Look at the "Today's one" section I newly added to my Daily Note. It lists notes awaiting review of their verification results, drafts in progress, and Permanent Note candidates.
If anything is awaiting review, read that note's "Verification" section. If something needs fixing, fix the body, and for each counterargument, check either "reflected in scope" or "not reflected."
If nothing is awaiting review, pick one candidate and write a new note from the Permanent Note template.

In the template, right after the field for the claim, I put three questions:

Why do I think so?
What experience of mine led me to this, or matched it?
In what cases does it not apply?

For verification, I run the following command in the vault folder. It inspects all drafts at once and writes the results into each note's "Verification" section.

claude -p "/zettelkasten verify --all" --allowedTools "Read,Glob,Grep,Edit,Write,WebSearch,WebFetch"

Verification takes time, so I stop working for the moment, and the back-and-forth in the moment goes away. In exchange, writing can continue even when the AI isn't running, and I can write from my iPhone or iPad. I set it up so it doesn't depend on where I am or what device I'm on.

For Permanent Note candidates, besides Fleeting Notes and the Inbox, I also included the directory where I save my AI conversations. I'm starting to feel this is the downside of splitting things into too many directories. If you're just starting out with Obsidian, I recommend keeping directories to a minimum. A single inbox is the easiest place to operate for stashing information and dropping insights.

The first note was carved out of a published article

Alongside writing new Permanent Notes from candidates, I decided to also carve them out of articles I've already published. Those articles are already in my own words. They're backed by research and already in publishable shape, so they become finished notes much faster than writing from a candidate from scratch.

I made the very first one from my Zenn article on Copier. Verification confirmed two points. First, a repository created from a GitHub template can't merge updates. Second, Copier can pull updates into a project after it has been generated.

Two counterarguments came back. One was that the update mechanism itself takes effort to maintain. I reflected that by adding "when there are few downstream projects" to the scope. The other pointed out that the update mechanism hasn't yet been tested with a major change. I finalized that one as-is, and I'll revise the note after trying updates with TypeScript 7.1 or 7.2. Being able to assume revision is thanks to lowering the bar. I'm grateful for that. There are times I just can't help wanting perfection, and at times like that, it becomes a shackle.

What I dropped, and what I haven't confirmed yet

There are two things I decided not to do:

Processing the remaining 182 Fleeting Notes. Two-year-old title-only memos can't be decoded even by the person who wrote them. I'll start from new insights and only pick up old memos when they become relevant.
Consolidating directories. I do think I split things too much, but stages can be managed with a property called status, so I leaned on Dataview to run things without moving any folders.

There are also things I haven't confirmed yet. The template and the list are brand new, and I haven't run the whole thing end to end inside Obsidian. Whether everything from entering a claim, to recording the seed, to moving it into a folder works as expected will take a few days of testing. I've also only tried the batch verification with zero drafts. I plan to set up scheduled runs myself once the system has been running for a while.

I'll judge whether this works by whether I have at least 8 verified Permanent Notes four weeks from now. By then, I should be able to share the verification results too.

Minimal Practical Ontology Sample with MCP and Claude. A mechanism to pass Business Definitions, not just data, to AI.

Takashi Abe — Fri, 09 Oct 2026 13:13:22 +0000

The word ontology has suddenly become familiar in recent years. It appears in data platform product descriptions and in discussions of AI agent design. However, I suspect few people have actually worked with one hands-on. In fact, I was one of them.

What you cannot understand through words alone, you must understand by running it. So I built a minimal ontology-like thing using only the bare essentials, and prepared a program that lets Claude act as the orchestrator. The program itself is published on GitHub. In this article, I will describe what that sample is, what it can and cannot do, and what insights emerged from it.

What Ontology Means Here

Let me first define the scope of the term. This is not philosophical ontology, nor OWL from the Semantic Web. What I am dealing with here is the more practical meaning used in the context of business systems.

In this article, ontology refers to something that declares the following three things:

Object types:
The kinds of things that appear in business—such as customers and orders—and their attributes.

Link types:
Relationships between things—for example, a customer places an order.

Action types:
Operations permitted on things—for example, canceling an order. This includes the conditions under which the action can be executed and what changes as a result.

The third one is the key. If you only have attributes and relationships, that is no different from an ER diagram or a schema. When you include what is allowed to be done in the declaration, the definition of data transforms into the definition of business. While a database says the order table has a status column, an ontology says only unshipped orders can be canceled. This difference is the subject of this article.

Let me touch on how this differs from similar concepts. Database input rules and validation ensure that a single piece of data has the correct form—for example, status can only be open, shipped, or cancelled. Business logic holds judgments like if already shipped, never allow cancellation again inside application code.

Both are very important for actual business execution, but the former only looks at the shape of data, while the latter buries judgments deep in code where they become a black box. An ontology can combine both into a single declaration—only unshipped orders can be canceled—and place it outside the code, in a form readable by both humans and AI. The significant difference is that what is being protected is not the database or the application, but the definition of the business itself. This difference in where things are placed is likely the key point that distinguishes the three.

Overview of the Sample Program

The configuration consists of only four elements.

First is the ontology definition. Object types, link types, and action types are written in a single YAML file. This is the main component; everything else is supporting cast.

Second is the instance store. I use PostgreSQL, but there are only two tables. An objects table that holds all types of objects as type, ID, attributes (JSONB), and a links table that holds relationships as type, from, to. Because I do not create a table for each type, adding a type to the YAML does not change the DDL.

Third is the ontology MCP server. It reads the YAML, wraps the database, and exposes only five generic tools to Claude:

describe_ontology: Returns a list of types, links, and actions
search_objects: Searches by attributes
get_object: Retrieves a single item
traverse: Follows links
execute_action: Validates preconditions, applies effects if passed, and records an audit log

I do not add tools for each type. If I designed it with separate searches for customers and orders, the tools would grow to fifty once types reached ten. By keeping it to five generic tools, the number stays at five no matter how many types are added.

Fourth is the orchestrator. For this project, I leave this entirely to Claude. Simply by registering the MCP server, Claude can call describe_ontology first, understand what is possible, and then operate accordingly.

With Docker Compose, the database and MCP server start up together.

What This Program Can Do

First, exploration. If you ask What types and actions does this ontology have?, Claude will explain the definition directly. For questions like List the Gold customers, Show me all orders from Yamada Trading, or Whose order is O1003?, it combines searching and link traversal to answer.

❯ Show me all orders from Yamada Trading

I will search for Yamada Trading orders from the ontology MCP server.

⏺ ontology - describe_ontology (MCP)
{
  "version": 1,
  "object_types": {
    "Customer": {
      "description": "A trading customer",
      "key": "customer_id",
      "properties": {
        "name": {
          "type": "string",
          "required": true
        },
        "tier": {
          "type": "enum",
          "required": true,
          "values": [
            "bronze",
            "silver",
            "gold"
          ]
        },
        "email": {
          "type": "string",
          "required": false
        }
      }
    },
    "Order": {
      "description": "An order from a customer",
      "key": "order_id",
      "properties": {
        "amount": {
          "type": "integer",
          "required": true
        },
        "status": {
          "type": "enum",
          "required": true,
          "values": [
            "open",
            "shipped",
            "cancelled"
          ]
        },
        "note": {
          "type": "string",
          "required": false
        }
      }
    }
  },
  "link_types": {
    "places": {
      "description": "A customer places an order",
      "from": "Customer",
      "to": "Order",
      "cardinality": "one_to_many"
    }
  },
  "action_types": {
    "cancel_order": {
      "description": "Cancel an unshipped order",
      "target": "Order",
      "parameters": {
        "reason": {
          "type": "string",
          "required": true
        }
      },
      "preconditions": [
        {
          "property": "status",
          "op": "eq",
          "value": "open"
        }
      ],
      "effects": {
        "status": "cancelled",
        "note": "$params.reason"
      }
    },
    "ship_order": {
      "description": "Mark an order as shipped",
      "target": "Order",
      "parameters": {},
      "preconditions": [
        {
          "property": "status",
          "op": "eq",
          "value": "open"
        }
      ],
      "effects": {
        "status": "shipped"
      }
    },
    "upgrade_tier": {
      "description": "Upgrade a customer tier by one level",
      "target": "Customer",
      "parameters": {},
      "preconditions": [
        {
          "property": "tier",
          "op": "ne",
          "value": "gold"
        }
      ],
      "effects": {
        "tier": "$next_enum"
      }
    }
  }
}

⏺ ontology - search_objects (MCP)(type: "Customer", filter: {"name":"Yamada Trading"})
{
  "result": [
    {
      "type": "Customer",
      "id": "C001",
      "name": "Yamada Trading",
      "tier": "gold",
      "email": "yamada@example.com"
    }
  ]
}

⏺ ontology - traverse (MCP)(type: "Customer", id: "C001", link: "places")
{
  "result": [
    {
      "type": "Order",
      "id": "O1001",
      "amount": 120000,
      "status": "shipped"
    },
    {
      "type": "Order",
      "id": "O1002",
      "amount": 45000,
      "status": "shipped"
    }
  ]
}

Yamada Trading (Customer ID C001, tier gold) has 2 orders.

┌──────────┬─────────┬────────────┬──────┐
│ Order ID │ Amount  │ Status     │ Note │
├──────────┼─────────┼────────────┼──────┤
│ O1001    │ 120,000 │ shipped    │ none │
├──────────┼─────────┼────────────┼──────┤
│ O1002    │ 45,000  │ shipped    │ none │
└──────────┴─────────┴────────────┴──────┘

The total amount is 165,000. There are no unshipped (open) or cancelled orders.

Next, action execution. If you submit Cancel all unshipped orders from Gold customers due to stock shortage, Claude searches for customers, follows links to gather orders, and executes cancel_order one by one. A human only needs to give this instruction in a single line of natural language.

❯ Cancel all unshipped orders from Gold customers due to stock shortage

I will search for Gold customers and cancel their unshipped (open) orders.

⏺ ontology - search_objects (MCP)(type: "Customer", filter: {"tier":"gold"}, limit: 500)
{
  "result": [
    {
      "type": "Customer",
      "id": "C001",
      "name": "Yamada Trading",
      "tier": "gold",
      "email": "yamada@example.com"
    },
    {
      "type": "Customer",
      "id": "C003",
      "name": "Suzuki Manufacturing",
      "tier": "gold",
      "email": "suzuki@example.com"
    }
  ]
}

⏺ ontology - traverse (MCP)(type: "Customer", id: "C003", link: "places")
{
  "result": [
    {
      "type": "Order",
      "id": "O1004",
      "amount": 80000,
      "status": "open"
    },
    {
      "type": "Order",
      "id": "O1005",
      "amount": 15000,
      "status": "cancelled"
    }
  ]
}

⏺ ontology - execute_action (MCP)(action: "cancel_order", target_id: "O1004", params: {"reason":"Stock shortage"})
{
  "ok": true,
  "object": {
    "type": "Order",
    "id": "O1004",
    "amount": 80000,
    "status": "cancelled",
    "note": "Stock shortage"
  }
}

There was only 1 unshipped order from Gold customers, and the cancellation is complete.

Status of affected Gold customers and orders

┌─────────────────────────┬──────────┬─────────┬────────────┬────────────┐
│ Customer                │ Order ID │ Amount  │ Before     │ After      │
├─────────────────────────┼──────────┼─────────┼────────────┼────────────┤
│ Yamada Trading (C001)   │ O1001    │ 120,000 │ shipped    │ No change  │
├─────────────────────────┼──────────┼─────────┼────────────┼────────────┤
│ Yamada Trading (C001)   │ O1002    │ 45,000  │ shipped    │ No change  │
├─────────────────────────┼──────────┼─────────┼────────────┼────────────┤
│ Suzuki Manufacturing    │ O1004    │ 80,000  │ open       │ cancelled  │
│ (C003)                  │          │         │            │            │
├─────────────────────────┼──────────┼─────────┼────────────┼────────────┤
│ Suzuki Manufacturing    │ O1005    │ 15,000  │ cancelled  │ No change  │
│ (C003)                  │          │         │            │            │
└─────────────────────────┴──────────┴─────────┴────────────┴────────────┘

The reason "Stock shortage" has been recorded in the note for O1004, and it is also in the audit log. All orders from Yamada Trading were already shipped, so there were no cancellation targets.

And it properly refuses when it understands the situation. For example, if you try to cancel a shipped order, the server-side precondition blocks this action. Claude reports: This order has already been shipped, so it could not be canceled. If you ask for a cancellation without providing a reason, since reason is a required parameter, Claude will ask you for the reason.

❯ Cancel O1001

⏺ ontology - get_object (MCP)(type: "Order", id: "O1001")
{
  "type": "Order",
  "id": "O1001",
  "amount": 120000,
  "status": "shipped"
}

O1001 cannot be canceled. The current status is shipped.

The cancel_order action has a precondition defined that it can only be applied to orders with status open. Even if executed, it would be rejected due to precondition failure, so no changes have been made.

The current state of O1001 is as follows:

┌──────────┬───────────────────────┬─────────┬────────────┐
│ Order ID │ Customer              │ Amount  │ Status     │
├──────────┼───────────────────────┼─────────┼────────────┤
│ O1001    │ Yamada Trading (C001) │ 120,000 │ shipped    │
└──────────┴───────────────────────┴─────────┴────────────┘

If you need to reverse a shipped order, this ontology does not have actions defined for returns or shipment reversal, so you would need to handle it through a different business workflow.

What I like most is this refusal. The anxiety about letting AI touch business data usually boils down to Will it do something unnecessary? In this mechanism, the means to do unnecessary things simply does not exist. There is no tool to directly rewrite the status; state can only change through actions. It is not safe because the AI is smart—it is safe because the logic side is built to be safe.

What This Program Cannot Do

Let me also clarify what it cannot do. This is a mix of things deliberately omitted to define the scope of the demo and things I simply have not gotten around to.

Creating and deleting objects. Register a new customer is not possible. Sample data is loaded via SQL.
Creating and deleting links. Link this order to Sato Industries is also not possible.
Range searches and partial matching. For orders over 100,000 yen, Claude would have to fetch everything and filter it himself. This breaks down as the number of records grows.
Preconditions spanning multiple objects. Conditions that look at linked items—like cancellation allowed only if the customer is Gold—cannot be written.
Transactions for batch execution. Execution is one item at a time, so if something fails midway, previous items are not rolled back.
Permissions. Who executed something is a fixed value. Who can do what is not implemented.

This list is also the list of what to do next. Range searches and preconditions that look at linked items in particular can be added just by slightly expanding the YAML vocabulary. I will fill these in as I feel this is missing while building.

Insights Gained from This Program

It is a small sample, but running it revealed three things.

First: What should be given to AI is not data but the definition of the world. If you give tables and SQL, the AI can do anything. Being able to do anything also means not knowing what it is allowed to do. When you give types and actions, the AI stops hesitating. Watching Claude read the result of describe_ontology and then proceed with exactly the steps I expected is just like someone reading a manual before starting work—literally someone who reads instructions and then acts.

Second: Five generic tools are enough. Initially I considered a design that created tools for each type. I did not do so because if I had to rewrite code every time I added a type to the YAML, there would be no point in separating it into YAML. In fact, I added a Product type and a restock action to the YAML, restarted the container, and Claude began handling the new type. Separating definitions from code makes changes easy and fast, and improves manageability.

Third: Audit logs should be built in from the start as part of actions, not added later. execute_action always leaves one line, whether it succeeds or is blocked by a precondition. Who, on what type, tried to do what, and what happened. In a world where AI operates, no one can explain why this happened without this record. I have not implemented it yet, but once who is added here, it will become nearly the complete audit record needed.

What Is Good About Ontology

Summarizing the discussion so far, the goodness of ontology lies in constraints.

I believe that turning routine work into programs is the original purpose of computers. Having written programs for nearly forty years, that thinking itself has not changed at all. What changed with the arrival of AI is that non-routine parts can now also be delegated to computers. For example: which customers, which orders, in what sequence to process. Things that humans normally think about and do manually can now be thought about by AI.

However, delegation requires boundaries. What is allowed, and what is not. Communicating those boundaries through natural language prompts is unreliable. Rather than asking Please do not cancel shipped orders, it is more certain to build it so cancellation is impossible. An ontology is a mechanism that writes those boundaries as declarations and has the system enforce them.

There is another good thing. When you write boundaries, the business becomes visible. To write a single line like only unshipped orders can be canceled, you need to confirm with the business people. Conversations emerge: Are there cases where shipped orders can also be canceled? Is that a different action called a return? This conversation is the most important and most easily skipped part when building systems. A single YAML can also become a tool to draw out that conversation. Also, this YAML itself could be called a business design document.

I believe the job of an architect is not to choose technology, but to express business as structure. An ontology is a place to put that structure in a form AI can read. That is why, even in the age of AI—no, precisely because it is the age of AI—I believe this tool will be effective.

Something to Try

If you have business data at hand, forget the table definitions for now and write out these three things on paper:

What kinds of things appear there?
What words connect things to things?
For those things, who, under what conditions, is allowed to do what?

If you can write the third one, that is already an ontology. If you cannot write it, that is where the business is ambiguous. Either way, you gain something.

The sample is on GitHub. Start it up with Docker Compose and ask Claude: Cancel all unshipped orders from Gold customers. And watch the shipped orders get properly refused. All the value of this mechanism is packed into that moment.

I Let Claude Code Grill Me, Then Built a Zenn-to-dev.to Crossposting Pipeline

Takashi Abe — Fri, 09 Oct 2026 07:20:49 +0000

I built a pipeline that translates the articles I write on Zenn into English and publishes them on dev.to too. I translate locally with Claude Code, and when I push to main, GitHub Actions publishes, updates, or unpublishes the article on dev.to.

My starting point was asherish's "Blog repository setup." Its setup, which bridges Zenn and dev.to with GitHub Actions, was a direct reference. But by the time I finished, my setup had made different calls from the original in three places:

No file recording dev.to article IDs; match by canonical_url every time
Only the original Japanese article holds the publication state
Detect a stale translation using a hash of the original article

The result is a setup where CI writes nothing back to the repository, and the only state lives on dev.to. In this post, I'll walk through the order in which I made those decisions, and how I used Claude Code along the way.

I settled the requirements by letting Claude Code ask me 30+ questions

The request I first gave Claude Code was just these three lines (originally in Japanese):

I want to create a GitHub Actions workflow that, when an article is added to articles/ for zenn.dev and becomes "published", posts a translated version of it to dev.to.
Use this as a reference.
Don't decide anything unclear by guessing; check everything with me.

I ran this request through grill-with-docs from Matt Pocock's skill collection for Claude Code. As the name suggests, it's a skill that grills the user with questions, closing off design branches one at a time. It doesn't ask everything at once; it only asks a batch of questions whose prerequisites are already settled. For example, until "where does translation happen?" is decided, it won't ask "where do we store the translation API key?"

Here are some of the questions I actually got:

Question	Claude's recommendation	My answer
Should the 18 existing published articles be crossposted too?	No	No
If the original is edited after publishing, update dev.to too?	Yes	Yes
Post to dev.to as a draft, or publish immediately?	Draft	Publish immediately
Where should images be served from (the repo is private)?	Make the repo public	Don't bring images
Translate in CI, or locally?	CI	Local Claude Code

For several questions, my answer differed from the recommendation. Drafts, for instance, were recommended "so you can review the machine translation once." But since I'd decided to translate locally, the review already happens before commit. That "where does translation happen?" question was one Claude added later, after reading the reference article. The reference didn't translate in CI, which contradicted my request ("translate and post with Actions"). That one question decided half of the design that followed.

Over five rounds, the questions went past 30. Each time an answer was settled, Claude added the terms to CONTEXT.md. That file pins down what words like "original article," "English version," "publish," and "crosspost" mean in this repository. You could call it a ubiquitous language, in domain-driven design terms. For decisions that would be hard to reverse later, it also recorded two ADRs (Architecture Decision Records: short documents capturing a decision and its reasoning).

As an aside, I'm writing a Zenn book about ADRs. I'll publish it once it's done.

ℹ️ grill-with-docs attaches a recommended answer to each question. You can keep going by just answering "sounds good" to the recommendation, so it isn't as tiring as the question count suggests. Conversely, if you don't want to accept recommendations blindly, make sure to read the reasoning attached to each one.

Translation stays out of CI: I review locally, then commit

My original, rough request was "translate and post with Actions," but in the end I took translation out of CI. The deciding factor was choosing to publish immediately on dev.to. If CI calls an LLM API to translate, English text that no human has ever read goes straight to publication.

So I split the roles like this:

flowchart LR
  A[Write the original article] --> B[/translate into English/]
  B --> C[Read the English version and commit]
  C --> D[Push to main]
  D --> E[Actions crossposts to dev.to]

Translation happens through the Claude Code skill /translate <slug>. The skill writes the translated body, and a script called translate-apply.ts converts Zenn syntax, adds frontmatter, and writes the result to articles_en/<slug>.md. The skill doesn't commit. I'm the one who reads the English version and commits it, and that's the only review checkpoint.

This way, I can safely use Claude Code on my subscription without setting up any translation API key. And there's no extra usage cost. The tradeoff is that if I forget to translate, the article just stays un-crossposted. I decided to catch that with the "on hold" warning described later.

Don't store dev.to article IDs; look them up by canonical_url

The reference setup stores the mapping between slugs and dev.to article IDs in .devto-mapping.json, and Actions commits that file back. From the second run onward, it uses that ID to update (PUT).

This approach caused me two problems. First, the Actions commit collides with my local main. Unless I pull after every push, my next push gets rejected. Second, what if the post (POST) to dev.to succeeds but committing the mapping fails? On the next run, the ID isn't found, so the same article gets posted again.

So in my setup, I chose not to keep a mapping at all. On every crosspost, it fetches my article list from the dev.to API and looks for the one whose canonical_url matches the URL of the original Zenn article. canonical_url is the URL that tells search engines "the original of this article is over here." Since every crossposted article always has one set, it works as a matching key.

sequenceDiagram
  participant GA as GitHub Actions
  participant API as dev.to API
  GA->>API: GET /api/articles/me/all
  API-->>GA: Article list (including unpublished)
  GA->>GA: Match against originals by canonical_url
  GA->>API: POST or PUT (only articles with changes)

Whether this works depends on how the list API on the dev.to side behaves. If unpublished articles weren't included in the list, an article that had been unpublished once would be judged "not on dev.to" when republished, and get posted twice. The documentation alone wasn't enough, so I had Claude read the source of Forem, which runs dev.to:

/api/articles/me/all also returns unpublished articles (the docs say "Unpublished articles will be at the top of the list")
The response includes published, body_markdown, tag_list (an array), and canonical_url
- Source: app/views/api/v1/articles/me.json.jbuilder
body_markdown is stored exactly as sent; no frontmatter gets added

That told me the diff check could also be done with a single list fetch. The costs are one list fetch per crosspost, and that if someone manually edits the canonical_url in the dev.to UI, matching breaks. The latter is written down in an ADR as an operational rule.

Only the original Japanese article holds the publication state

In the reference setup, the English version's frontmatter also has published, and CI verifies that it matches the Japanese version. If they don't match, publishing stops.

In the option I chose, the English version doesn't have published at all. Actions always reads the original article's published and makes dev.to match it. If there's only one source to begin with, there's nothing to check for mismatches. Setting the original back to published: false is all it takes to unpublish on dev.to as well.

As a result, the English version's frontmatter has just three fields:

articles_en/.md

---
title: 'Why "Harness": a note'
tags:
  - ai
  - mcp
source_hash: edf3ae74a6a6...
---

What happens to each article is decided as shown below. Only "slugs that have an English version" are processed. The 18 existing articles have no English version, so they naturally fall out of scope without any exclusion list.

flowchart TD
  A[Has English version] --> B{Original is published}
  B -- Yes --> C{Exists on dev.to}
  B -- Unpublished or deleted --> D{Published on dev.to}
  C -- No --> E[POST and publish immediately]
  C -- Yes --> F{Content changed}
  F -- Yes --> G[Update with PUT]
  F -- No --> H[Do nothing]
  D -- Yes --> I[Unpublish with PUT]
  D -- No --> H

The diff check compares four things: title, body, tags, and publication state. The reference setup PUT every published article on every push, but that needlessly changes the updated timestamp on dev.to as well. It also pushes you closer to dev.to's rate limits (by default, 9 article creations and 30 updates per 30 seconds).

Catch stale translations with a hash of the original

Sometimes I fix the original after publishing and forget to regenerate the English version. To catch this, I record the original article's hash at the time the English version was made, as source_hash in the English version. At crosspost time, it computes the current original's hash and warns if they don't match.

So what should that hash be computed from? The first thing that comes to mind is a hash of the whole original file. But then just flipping published: false to true changes the hash. If you prepare the translation ahead of time and then publish, you'd get a "translation is stale" warning every single time.

So I narrowed the hash input down to the title and body:

$$
h = \mathrm{SHA256}\left(\mathrm{JSON}({\,\mathit{title},\ \mathit{body}\,})\right)
$$

Changing published, topics, or emoji leaves $h$ unchanged; it only changes when the body or title changes. The tests state exactly this property:

scripts/lib/hash.test.ts

it("published を切り替えてもハッシュは変わらない", () => {
  const published = original.replace("published: false", "published: true");

  expect(computeSourceHash(published)).toBe(computeSourceHash(original));
});

A stale English version is still crossposted as-is, with a warning. If crossposting stopped instead, fixing even a single typo would leave dev.to un-updated until the translation was regenerated.

Pin down Zenn syntax conversion with tests

dev.to doesn't understand Zenn's own syntax, so conversion is needed.

Zenn	On dev.to
`:::details タイトル`	`{% details タイトル %}` … `{% enddetails %}`
`:::message` (`alert`)	A blockquote prefixed with ℹ️ (⚠️)
Fence info `ts:src/index.ts`	A bold `src/index.ts` right before the code
`@[card](URL)`	A plain link
`@[youtube](ID)` etc.	`{% embed URL %}`
`![alt](/images/...)`	A note saying "see the original Zenn article for the image"

Images are replaced with a note because the repository where I manage my Zenn articles is private, so dev.to can't fetch images from it. Making the repository public was an option, but it would expose unpublished drafts too, so I passed on it.

The conversion isn't left to Claude Code; it's a regex-based script. With an LLM, there's no guarantee the same input produces the same output every time. A deterministic program or script lets you pin its behavior down with tests.

The trickiest part of the conversion was the constraint that nothing inside code blocks gets converted. Sometimes, like in this very post, I write code examples that explain Zenn syntax itself:

```md
:::details これは記法の説明なので、変換してはいけない
:::
```

So I went with a somewhat fiddly mechanism: before conversion, each code block is stashed away and replaced with a one-line placeholder (a number wrapped in the Unicode Private Use Area characters U+E000 and U+E001), and restored after conversion finishes.

Stash-and-restore code (excerpt)

scripts/lib/convert.ts

export function convertZennToDevto(markdown: string, options: ConvertOptions): string {
  const { text, blocks } = stashCodeBlocks(markdown);
  const converted = [
    (t: string) => convertLocalImages(t, options.originalUrl),
    convertEmbeds,
    convertDetails,
    convertMessages,
  ].reduce((acc, convert) => convert(acc), text);
  return converted.replace(PLACEHOLDER, (_m, prefix: string | undefined, i: string) =>
    prefix ? quoteLines(prefix, blocks[Number(i)]) : blocks[Number(i)],
  );
}

This approach has a pitfall. Since :::message is converted into a blockquote, the placeholder line inside it also starts with >. But when the placeholder is restored, the second and subsequent lines of the code block don't have >. The blockquote gets cut off mid-code. On restore, it looks at the leading > and re-applies it to every line of the code.

What you didn't decide shows up during implementation

Writing tests first, gaps surfaced that even 30+ questions hadn't closed. No matter how good the architect on the team is, design can't define every implementation problem up front. Some things you only find out by actually implementing them, and that happens in the real world. It happens just as naturally in AI-driven development.

The biggest one was how to handle "on hold." During the grilling phase, I'd decided that "a published article without an English version gets its crosspost put on hold, with a warning." But once I wrote the tests, all 18 existing articles matched that condition. As-is, every push would line up 18 warnings.

Claude Code stopped implementing and came back with four options:

Warn only about articles changed in that push
Keep an exclusion list
Don't warn
Warn about everything every time (as agreed)

I chose 1. It takes the diff against the previous commit with git diff, and warns only about changed originals that have no English version.

After implementation, I also had a review agent look it over. Of its 10 findings, I fixed 7. The main four:

If a force push removes the previous commit, git diff fails and the whole job stops. Since the warning is a supporting feature, crossposting now continues even if it fails
A broken YAML in just one original article stopped crossposting for every article. It's now treated as a per-article error
If dev.to saves tags in a different order or changes the trailing newline, articles with no changes get updated every time. Those two are now excluded from the comparison
Zenn lets you nest :::message inside ::::details, but the outer one wasn't being converted

In the end there were 41 tests, with 99% line coverage and 93% branch coverage. Things with small impact, or that recover on a rerun, such as retrying on 5xx errors, were skipped, with the reasons written down.

On the first crosspost, the tags silently vanished

I tried the first crosspost with ""Is That a Harness Too?" Making Sense of Harness Engineering for AI Agents (Japanese original)." I committed the English version, merged the PR, and the push to main triggered Actions. The article is published as ""Is That a Harness Too?" Making Sense of Harness Engineering for AI Agents." The canonical_url pointed to the original Zenn article, and no Zenn syntax was left in the body.

But when I actually ran it, there wasn't a single tag on it. The English version's frontmatter listed four: ai, agents, llm, and architecture. The API didn't return an error, so there was nothing in the Actions logs to tip me off.

The cause was how the tags were sent. The dev.to API docs say tags is "a comma-separated string." The first implementation followed that and sent "ai,agents,llm,architecture". But reading Forem's controller, it only accepts an array:

app/controllers/concerns/api/articles_controller.rb

allowed_params = [
  :title, :body_markdown, :published, :series,
  :main_image, :canonical_url, :description, { tags: [] },
  # ...
]

When a key is declared as { tags: [] }, Rails strong parameters silently drop a string value instead of raising an error. I'd had Claude read the source to verify the list API, yet blindly trusted the docs for the API that sends articles. Honestly, though, this one's on the docs. Leaning on Claude Code this time is what led me to read the source code at all; a human developer would normally have no choice but to trust the docs unless there were prior reports. What a pain.

This bug had one more annoying side effect. Since the tags on dev.to stayed empty, the diff check saw "tags differ" every time. Even with nothing changed, a PUT would keep firing on every push. I fixed it to send tags as an array and changed the test expectations to arrays too. Thanks to that, the tags are now assigned properly.

Looking back

In one sentence, the setup keeps translation in human hands locally, and leaves CI with just one job: mirroring the original article's publication state to dev.to. Since CI writes nothing back, there's no mapping file, no bot commits, and no collisions with my local main.

Starting from the reference setup was the right call. Having that foundation is exactly what let me ask, for each decision like "commit a mapping file" or "keep published in two places," whether it fit how I work. And the grilling skill is what laid out those questions without missing any.

If you're thinking about running Zenn and dev.to side by side the same way, I'd suggest deciding two things first: "where does translation happen?" and "where does the dev.to-side state live?" The rest of the decisions should get much easier after that.

"Is That a Harness Too?" Making Sense of Harness Engineering for AI Agents

Takashi Abe — Fri, 09 Oct 2026 05:16:52 +0000

When sales says "everything is a harness," they're not wrong. It's just too broad

Lately I keep hearing the same lines from sales folks around me: "Oh, that's harness engineering," or "Are you really thinking about harness engineering?" What exactly do they mean by it? For some people, building an MCP server is harness engineering. So is wiring up RAG. So is adding guardrails. Everything is harness engineering.

Let's get on the same page first.

By harness engineering, I don't mean test harnesses, and I don't mean Harness.io, the CI/CD product. I mean Harness Engineering in the sense of what it takes to turn an AI agent into a system that actually works in practice.

With that settled: in the broad sense, the sales instinct isn't wrong. But taken at face value, it's far too broad to be useful as an IT architecture term. It ends up meaning roughly "we're doing something around AI agents."

So I tried defining it again:

Harness Engineering is the design of the execution environment and feedback loops around a probabilistic AI model, so that it becomes a "work-executing agent" that is "controllable," "verifiable," and "observable."

This isn't a technique for making AI smarter. It's a technique for taking an AI that is admittedly smart but unreliable, and containing it so it can do real work. Below is how I arrived at that one sentence, plus a quick test for when sales tells you "that's a harness."

A harness is the whole loop outside the model

As of 2026, there's a formula you see everywhere:

$$
Agent = Model + Harness
$$

LangChain uses almost exactly this phrasing. Microsoft defines an Agent Harness as "the execution foundation that makes a language model function as an AI agent that can actually get work done." It's made up of the pieces responsible for conversation state, context, tool calls, approval policies, multi-step progress, and so on.

Roughly sketched, it looks like this:

flowchart TD
    E[User / Event] --> C
    M([Model])
    subgraph Harness
        C[Context]
        A[Action / Tool]
        R[Result / Observation]
        V{Validate / Evaluate}
        RT[Retry]
        F[Finish]
        ES[Escalate]
    end
    C --> M
    M --> A
    A --> R
    R --> V
    V -->|Failed| RT
    V -->|Done| F
    V -->|Risky| ES
    RT --> C

This entire outer loop is the harness.

The model's job is to figure out "what's probably the right next move." The harness's job is to decide what to show it, what to let it do, what to forbid, how to check the results, what to do on failure, and when to stop. The automation I've been building lately by combining Jev with n8n is, I'd argue, exactly what you'd call harness engineering.

The core is the control loop, not the tool connections

Get this wrong and Harness Engineering turns into "every AI-adjacent technology, bundled."

Google Cloud describes building a harness as "wrapping a language model in scripts that manage its inputs, outputs, and tool execution." Tools are executed via MCP and the like, the results are appended to the conversation history, and everything is fed back to the model. For enterprise use, it's positioned as the layer that manages state, permissions, and tool execution, and because it owns all input and output, it also makes monitoring and cost tracking easier.

So if you think about it in stages, the boundary comes into view. This alone is just "API integration":

flowchart LR
    LLM --> API

Once you get here, you're gradually entering harness territory:

flowchart TD
    LLM --> EX[Call API]
    EX --> CK[Check result]
    CK --> Q{Goal achieved?}
    Q -->|No| NX[Decide next action]
    Q -->|Yes| FIN[Finish]

And if you've designed all the way to the third stage below, I think you can pretty clearly call it Harness Engineering:

flowchart TD
    P[Check permissions] --> E[Execute]
    E --> V[Verify result]
    V --> FX[Fix if failed]
    FX --> ES[Escalate to a human if risky]
    ES --> LG[Store logs and eval data]

It doesn't end once things are connected. You look at what came back, decide the next action, and take care of retries and cutoffs. That "taking care of it" part is the core.

MCP, RAG, and guardrails are all just parts of a harness

In practice, it helps to break down what a harness decides like this:

Area	What the harness decides
Instructions	What goal the agent acts toward
Context	What to show the model this time
Retrieval	What to pull from internal docs and DBs
Tools	What it can execute
Identity / Permission	Whose permissions it acts with, and how far
Orchestration	In what order and loops it runs
State / Memory	How state from previous runs is kept
Guardrails	What is forbidden
Verification	How to check the result is correct
Retry / Recovery	How to roll back on failure
Human approval	Where a human steps in
Observability	What gets kept as logs and traces
Evaluation	Whether the agent behaves as expected
Termination	When the job counts as done

Microsoft's current Agent Harness likewise groups planning, file memory, tool approval, OpenTelemetry, web search, skills, background agents, shell execution, looping, and more as harness capabilities.

Looking at this table, it's clear that MCP is not the harness itself. MCP is one mechanism for connecting the tools a harness uses. RAG is the same: one part of Context / Retrieval. Guardrails are one part. Memory is one part.

Whether you're talking with sales or with customers, keeping these separate makes life easier as an architect. "We connected MCP" and "we designed a harness" simply don't belong in the same sentence.

Prompt Engineering and Context Engineering both live inside the harness

The relationship among the three is easiest to understand as nesting:

flowchart TD
    H[Harness Engineering] --> P[Prompt / Instruction Engineering]
    H --> C[Context Engineering]
    C --> RAG
    C --> MEM[Memory]
    C --> PD[Progressive Disclosure]
    H --> T[Tool Engineering]
    T --> API
    T --> MCP
    H --> O[Orchestration]
    H --> G[Guardrails / Permissions]
    H --> EV[Evaluation / Verification]
    H --> OB[Observability / Recovery]

Birgitta Böckeler's breakdown, published on everyone's favorite Martin Fowler site, splits Harness Engineering into Guides and Sensors. Her framing is scoped specifically to working with coding agents.

A Guide is feedforward: it steers the agent in the right direction before it fails. Rules, documentation, system prompts, Skills, and tool specs all fall here.

A Sensor is feedback: it observes what happened and flags mistakes. Tests, linters, logs, metrics, reviews by another AI, and so on.

flowchart LR
    G["Guide (feedforward)"] --> AG[Agent]
    GO[Goal] --> AG
    AG --> AC[Action]
    AC --> S["Sensor (feedback)"]
    S --> AG

Giving instructions is only half a harness. It becomes a harness only once you've built the part where the agent acts, you observe, and it corrects itself.

Polishing prompts strengthens the Guide. If that's all you do, nobody will notice when the agent gets something wrong.

Why harnesses, why now? Because LLMs got smarter

It's a bit paradoxical, but the reason is that models got smarter.

Back when models were weak, it looked like this:

flowchart LR
    HU[Human] --> AI
    AI --> AN[Answer]

A human asks, the AI answers, and if it's wrong, the human catches it. That was enough.

Once models are strong enough, it looks like this:

flowchart TD
    AI --> S[Investigate]
    S --> J[Decide]
    J --> E[Execute]
    E --> C[Check result]
    C --> N[Next decision]

Now that they can act this autonomously, the question has shifted from "can the AI answer?" to "how much can we hand over to the AI?"

The Harness Engineering post OpenAI published in February 2026 is about exactly this. When they had Codex write code, early progress was slow not because Codex lacked the ability, but because the environment wasn't described well enough. In the end, they built testing, verification, review, feedback handling, and failure recovery into the system side as part of the development loop.

In other words, the problem moved from model capability to system engineering. That, I think, is why Harness Engineering is suddenly getting so much attention. And it's good news for architects: we can't touch the model's internals, but system engineering is our home turf.

Sales support, refunds, and incident response: where the boundary shows up

Let's walk through some concrete examples.

Sales support agent

"Prep me for the next meeting with Company X."

On its own, that's just using an LLM. Build a harness, and you get a flow like this:

flowchart TD
    A[Fetch Account from CRM] --> B[Fetch Contacts / Opportunities]
    B --> C[Fetch past meetings]
    C --> D[Check internal access rights]
    D --> E[Search external sources if needed]
    E --> F[Draft meeting hypotheses]
    F --> G[Cross-check against sources]
    G --> H[Draft CRM updates]
    H --> I[Human approves]
    I --> J[Update CRM]

The CRM itself is not the harness. The harness is the mechanism that controls when the CRM is accessed, under whose permissions, what gets fetched, and how much the agent is allowed to update.

Customer support agent

Say a customer writes, "I was double-charged, refund me."

A bare model would probably fire back "We're so sorry. We'll refund you" right away. Anyone can say that. An agent that can actually issue a refund looks like this:

flowchart TD
    A[Verify identity] --> B[Fetch order]
    B --> C[Check payment history]
    C --> D[Fetch refund policy]
    D --> E[Calculate refundable amount]
    E --> F[Threshold check]
    F --> G[Human approval if needed]
    G --> H[Call payment API]
    H --> I[Re-fetch to confirm the refund actually happened]
    I --> J[Update CRM]
    J --> K[Reply to customer]

That step near the end, "re-fetch to confirm the refund actually happened," matters enormously. "We called the refund API" and "the refund went through" are two different things.

In Harness Engineering, verification matters more than action.

Incident response agent

For "The website is slow. Find out why," the following flow is relatively safe:

flowchart TD
    A[Fetch metrics] --> B[Fetch logs]
    B --> C[Inspect traces]
    C --> D[Form hypotheses]
    D --> E[Investigate further]
    E --> F[Identify likely causes]
    F --> G[Draft a fix]

Because it only reads and thinks.

But once you allow actions that affect running processes, the story changes:

kubectl rollout restart

The harness needs to check:

Is this a production change?
What's the blast radius?
Can it be rolled back?
Does it need approval?
Did things return to normal afterward?

Only when you can answer all five does it hold up as an enterprise system.

What all three examples share is that between the agent's "read" phase and its "change" phase, there's a layer of permissions, verification, and human approval. That layer in between is the harness itself.

A harness is never "done"

Here are the pros and cons of a harness side by side:

Pros	Cons
Improves performance independently of model changes	The system gets considerably more complex
Lets you raise agent autonomy safely	More to operate: traces, evals, permissions, state, and more
Improves reproducibility, auditability, explainability	Model improvements can turn an old harness into a hindrance
Reduces human review work	Excessive rules can kill the model's capabilities
Feeds failures back into the next Guide / Sensor	The harness itself needs testing

The third con is especially easy to miss.

Anthropic pointed out in April 2026 that a harness encodes assumptions about "what Claude can't do on its own," so as models improve, those assumptions need to be revisited.

They also gave a real example. They had added context resets to deal with Sonnet 4.5's habit of sensing the context limit and wrapping up work early. But with Opus 4.5, that habit disappeared, and the resets became dead weight.

That's why a harness is never finished once built. You need to trim it down or rebuild it alongside model updates. What you're maintaining is "the parts built on the assumption that the AI will get things wrong."

The problem with "everything is a harness" is that the word stops being useful

In conversations with sales, this is probably the most important part.

Böckeler's article itself says that "Agent = Model + Harness is a very broad definition, so it's worth narrowing it down by type of agent." She then explicitly limits her own definition to the bounded context of working with coding agents. I think that's the right approach.

For example, calling "I built an MCP server" Harness Engineering isn't wrong.
But the moment you label every item below as "Harness Engineering," the term becomes nearly synonymous with "we're doing something around AI agents." A word that doesn't tell you what it refers to is useless in a design conversation.

REST API development
IAM
RAG
Prompt
MCP
Workflow
Logging
Monitoring
Evaluation

So how about distinguishing them like this?

What you're doing	What to call it
Improving instructions	Prompt / Instruction Engineering
Selecting information, RAG, Memory	Context Engineering
MCP / API connections	Tool Integration
Procedures, routing	Agent Orchestration / Workflow
Permissions, prohibitions	Guardrails / Governance
Evaluation	Agent Evaluation
Traces, metrics	Agent Observability / AgentOps
Combining all of these to control autonomous execution	Harness Engineering

Harness Engineering isn't so much the name of an individual technology as a higher-level concept: designing the control system that integrates all of these to make an agent's behavior work. Framed that way, everything falls neatly into place.

It's fine for sales to tell a customer "you need Harness Engineering." The architect's job is to break that one line down into the rows of the table above and show what's covered and what's missing.

Eight questions to answer "Is that a harness?"

When sales says "this is Harness Engineering," checking these in order seems to sort things out:

Priority	Question
1	What does the agent have to achieve to be "done"?
2	What can the agent see?
3	What can the agent execute?
4	What must it not execute?
5	How are execution results verified?
6	How does it retry / recover when it gets things wrong?
7	Where does it escalate to a human?
8	Can its decisions and actions be traced afterward?

If all eight are designed, then "I see, that is Harness Engineering" is a fair verdict.

If, on the other hand, it's just "we connected the CRM via MCP," that's Tool Integration. It's one of the parts that make up a harness, but it isn't Harness Engineering as a whole. That's how I'd sort it.

The order of these eight questions matters, too. For an agent with no defined "done" condition (question 1), there's no way to design "verification" (question 5) or "traceability" (question 8). That's why you always start with question 1.

Harness Engineering is really just good old system design

Harness Engineering is a new name, but from an architect's point of view, it's not all that foreign. Isn't it what we've been doing all along?

Let's list what we've always done:

Define boundaries
Define permissions
Manage state
Detect failures
Retry
Roll back
Monitor
Test
Escalate to humans

That's system design, plain and simple. Designing batch reruns, compensating transactions, alerting for operations monitoring: all of it fits on this list.

There is, however, one big difference.

Traditionally, humans defined a program's behavior as code. In an agentic system, part of that behavior is delegated to a non-deterministic model. That's why you need a strong control system around it. That's the harness.

I've been writing programs for over 40 years, and I believe that turning routine work into programs is what computers are fundamentally for. That belief hasn't changed in the age of AI. If anything, it's become clearer.

Whatever can be made routine, you lock down with deterministic, definitive programs, just as before. Only the judgments that can't be made routine get handed to a probabilistic model. And the results of those delegated judgments get verified, again, by deterministic programs. A harness is the design of that "deterministic part." Let computers do what they're good at, and don't let uncertain things run loose as they are. Drawing that line has always been the architect's job.

Seen this way, the difference among the three terms fits in a single line.

If Prompt Engineering is "how you instruct the AI" and Context Engineering is "what you show the AI," then Harness Engineering is the craft of designing "what kind of world you put the AI to work in."

With this definition, I think we can finally push back on the "everything is a harness" problem.

[Tailscale] Complete Guide to VPN Connection to Home LAN with Subnet Router

Takashi Abe — Fri, 09 Oct 2026 02:23:39 +0000

Accessing Your Home LAN from Outside with Tailscale Subnet Router

I want to access my home NAS or server while away from home. But VPN setup is difficult... I do not have a VPN router either... Tailscale solves these problems.

In this article, I will explain how to build an environment using Docker that allows you to access your entire home LAN from outside using Tailscale Subnet Router functionality.

1. Requirements Overview

What We Want to Achieve

VPN connection to home LAN (192.168.x.x) from smartphone/PC while away
Name resolution for internal domains (*.example.local) using home DNS server
Privacy protection so family members can use it but cannot see each other devices

Users

User	Usage	Remarks
Admin	Remote management, all LAN access	Full admin privileges
Family	Simple LAN access (NAS, etc.)	Limited privileges, privacy protection between terminals

Functional Requirements

Requirement	Description
Access to home LAN from outside	Reachable to all devices in 192.168.x.0/24
Inter-user communication blocking	For privacy protection, family devices cannot communicate with each other
Split DNS	Only specific domains resolved by home DNS when connected to Tailscale
Subnet Router only	Exit Node (all traffic forwarding) not required

Technical Decisions

Item	Decision	Reason
Container runtime	Docker	Easy management, reproducibility
Network mode	host	Required for Subnet Router
State persistence	Named Volume	Re-authentication unnecessary on restart
Health check	Built-in endpoint	Easy monitoring integration

2. Architecture Overview

Overall Configuration Diagram

Communication Flow

Component Roles

Component	Role	Remarks
Tailscale Container	Subnet Router, forwards traffic from Tailnet to LAN	Uses SNAT
DNS Server (Unbound)	Internal domain name resolution	Split DNS target
UFW/iptables	Firewall, controls forwarding	Important settings required

Importance of SNAT (Source Network Address Translation)

Tailscale enables SNAT by default (--snat-subnet-routes=true). This is equivalent to MASQUERADE (IP masquerade / NAPT) in Linux iptables.

Setting	Behavior	Notes
SNAT enabled (default)	Source IP becomes Subnet Router IP	No additional settings needed on LAN devices
SNAT disabled	Tailscale IP (100.x.x.x) is sent as-is	Static routes must be set on LAN routers and devices

SNAT enabled is recommended. No additional settings needed on LAN devices.

3. Design Considerations

3.1 Understanding Split DNS

Split DNS is a mechanism to resolve only specific domains with specific DNS servers.

Benefits:

Normal internet access uses fast local DNS
Only home internal domains resolved by home DNS
No impact on internet speed even when connected to VPN

3.2 Complex Relationship Between UFW and iptables

This is the biggest pitfall. In environments using Docker, multiple firewall layers exist:

Settings Requiring Attention

Layer	Setting Location	What to Set
UFW INPUT	ufw allow	WireGuard port (41641/udp)
UFW FORWARD	/etc/default/ufw	DEFAULT_FORWARD_POLICY=ACCEPT
DOCKER-USER	/etc/ufw/after.rules	RETURN rules for Tailscale CGNAT

3.3 DNS Server ACL Settings

If using DNS servers like Unbound, you need to allow queries from Tailscale CGNAT (100.64.0.0/10).

With Split DNS, Tailscale clients send queries directly to the DNS server. At this time, the source IP becomes a CGNAT address (100.x.x.x).

3.4 Auth Key Management

Important: If state is persisted with Docker Named Volume, re-authentication is not required on container restart. Auth Key is only needed in the following cases:

Initial deployment

When Named Volume is deleted

When device is deleted from Tailscale Admin Console

4. Configuration Details

From here, I will explain specific configuration methods.

4.1 Tailscale Admin Console Settings

4.1.1 Issuing Auth Key

Access Tailscale Admin Console
Settings → Keys → Generate auth key
Issue with the following settings:

Item	Setting
Description	home-router
Expiration	90 days (or as needed)
Reusable	Off (for security)
Ephemeral	Off (persistent device)
Pre-approved	On
Tags	tag:subnet-router

Save the issued key securely (format: tskey-auth-xxxxx).

4.1.2 ACL Settings

Set the following in Admin Console → Access Controls:

{
  "groups": {
    "group:admin": ["your-admin-email@example.com"],
    "group:family": ["family-email@example.com"]
  },

  "tagOwners": {
    "tag:subnet-router": ["group:admin"]
  },

  "hosts": {
    "home_network": "192.168.x.0/24"
  },

  "acls": [
    {
      "action": "accept",
      "src": ["group:admin", "group:family"],
      "dst": ["home_network:*"]
    },
    {
      "action": "accept",
      "src": ["tag:subnet-router"],
      "dst": ["*:*"]
    }
  ]
}

Points:

group:admin and group:family can access home LAN
By not defining inter-terminal communication rules, default deny is applied and mutual communication is blocked

4.1.3 DNS Settings (After Deployment)

Set the following in Admin Console → DNS:

Item	Setting
Add Nameserver	Custom: 192.168.x.53 (home DNS server IP)
Restrict to domain	example.local
Override local DNS	Off

4.2 Server-Side Preparation

4.2.1 Enabling IP Forwarding

# Create configuration file
sudo tee /etc/sysctl.d/99-tailscale.conf << 'EOF'
net.ipv4.ip_forward = 1
net.ipv6.conf.all.forwarding = 1
EOF

# Apply immediately
sudo sysctl -p /etc/sysctl.d/99-tailscale.conf

# Verify
sysctl net.ipv4.ip_forward
# Output: net.ipv4.ip_forward = 1

4.2.2 TUN Device Verification

# Verify TUN device exists
ls -la /dev/net/tun

# Create if it does not exist
sudo mkdir -p /dev/net
sudo mknod /dev/net/tun c 10 200
sudo chmod 666 /dev/net/tun

4.3 Docker Configuration

4.3.1 Directory Creation

sudo mkdir -p /opt/tailscale
cd /opt/tailscale

4.3.2 Creating docker-compose.yml

sudo tee /opt/tailscale/docker-compose.yml << 'EOF'
services:
  tailscale:
    image: tailscale/tailscale:v1.94.1
    container_name: tailscale
    hostname: home-router
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
      - NET_RAW
    network_mode: host
    volumes:
      - tailscale_data:/var/lib/tailscale
      - /dev/net/tun:/dev/net/tun
    environment:
      - TS_AUTHKEY=tskey-auth-xxxxxxx # Set Auth Key here
      - TS_STATE_DIR=/var/lib/tailscale
      - TS_ROUTES=192.168.x.0/24
      - TS_USERSPACE=false
      - TS_ACCEPT_DNS=false
      - TS_EXTRA_ARGS=--port=41641
      - TS_ENABLE_HEALTH_CHECK=true
      - TS_ENABLE_METRICS=true
      - TS_LOCAL_ADDR_PORT=[::]:9002

volumes:
  tailscale_data:
EOF

Configuration Item Descriptions:

Item	Value	Description
image	tailscale/tailscale:v1.94.1	Use specific version
network_mode	host	Required for Subnet Router
cap_add	NET_ADMIN, NET_RAW	Network operation privileges
TS_ROUTES	192.168.x.0/24	Subnet to advertise
TS_USERSPACE	false	Use kernel mode (recommended)
TS_ACCEPT_DNS	false	Do not use Tailscale DNS on server side

Important Settings:

Environment Variable	Description	Notes
TS_AUTHKEY	Authentication key	Needed only for initial deployment
TS_STATE_DIR	State storage location	Authentication state is persisted
TS_ROUTES	Advertised routes	LAN subnet to be accessible

4.3.3 Starting the Container

cd /opt/tailscale
sudo docker compose up -d

# Check logs
sudo docker compose logs -f

4.3.4 Operation Verification

# Check container status
sudo docker ps | grep tailscale

# Check Tailscale status
sudo docker exec tailscale tailscale status

# Expected output example:
# 100.x.x.x  home-router  your-tailnet.ts.net  linux  -
# 100.x.x.x  iphone       your-tailnet.ts.net  iOS    idle

4.3.5 Route Approval

After starting the container, enable 192.168.x.0/24 in Tailscale Admin Console → Machines → home-router → Edit route settings.

4.4 iptables/UFW Configuration

4.4.1 Changing UFW Routed Policy

Since Subnet Router forwards packets, UFW routed policy needs to be changed to allow.

# Check current settings
sudo ufw status verbose
# Default: deny (incoming), allow (outgoing), deny (routed) ← routed is deny

# Edit /etc/default/ufw
sudo sed -i 's/DEFAULT_FORWARD_POLICY="DROP"/DEFAULT_FORWARD_POLICY="ACCEPT"/' /etc/default/ufw

# Reload UFW
sudo ufw reload

# Verify
sudo ufw status verbose
# Default: deny (incoming), allow (outgoing), allow (routed) ← OK if allow

4.4.2 Allowing WireGuard Port

sudo ufw allow 41641/udp comment "Tailscale WireGuard"

4.4.3 DOCKER-USER Chain Configuration (Important)

When using Docker, the DOCKER-USER chain filters traffic from outside. Traffic from Tailscale CGNAT (100.64.0.0/10) needs to be allowed.

# Edit /etc/ufw/after.rules
sudo tee -a /etc/ufw/after.rules << 'EOF'

# BEGIN TAILSCALE DOCKER INTEGRATION
*filter
:DOCKER-USER - [0:0]
-A DOCKER-USER -j RETURN -s 10.0.0.0/8
-A DOCKER-USER -j RETURN -s 172.16.0.0/12
-A DOCKER-USER -j RETURN -s 192.168.0.0/16
-A DOCKER-USER -j RETURN -s 100.64.0.0/10

-A DOCKER-USER -j DROP -p tcp -m tcp --tcp-flags FIN,SYN,RST,ACK SYN -d 192.168.0.0/16
-A DOCKER-USER -j DROP -p tcp -m tcp --tcp-flags FIN,SYN,RST,ACK SYN -d 10.0.0.0/8
-A DOCKER-USER -j DROP -p tcp -m tcp --tcp-flags FIN,SYN,RST,ACK SYN -d 172.16.0.0/12
-A DOCKER-USER -j DROP -p udp -m udp --dport 0:32767 -d 192.168.0.0/16
-A DOCKER-USER -j DROP -p udp -m udp --dport 0:32767 -d 10.0.0.0/8
-A DOCKER-USER -j DROP -p udp -m udp --dport 0:32767 -d 172.16.0.0/12

-A DOCKER-USER -j RETURN
COMMIT
# END TAILSCALE DOCKER INTEGRATION
EOF

# Reload UFW
sudo ufw reload

# Verify
sudo iptables -L DOCKER-USER -v -n

Important: Without -A DOCKER-USER -j RETURN -s 100.64.0.0/10, UDP packets (including DNS) from Tailscale clients to LAN will be dropped.

4.5 Unbound (DNS Server) Configuration

When using Split DNS, the DNS server needs to allow queries from Tailscale CGNAT (100.64.0.0/10).

4.5.1 Unbound ACL Configuration

# Edit /etc/unbound/unbound.conf.d/access-control.conf
sudo tee /etc/unbound/unbound.conf.d/access-control.conf << 'EOF'
server:
    # Localhost
    access-control: 127.0.0.0/8 allow

    # LAN
    access-control: 192.168.x.0/24 allow

    # Docker networks
    access-control: 172.16.0.0/12 allow

    # Tailscale CGNAT (for Split DNS)
    access-control: 100.64.0.0/10 allow

    # Deny all others
    access-control: 0.0.0.0/0 refuse
EOF

# Restart Unbound
sudo systemctl restart unbound

# Verify
sudo systemctl status unbound

4.5.2 DNS Server UFW Configuration

If the DNS server is on a separate machine, UFW on that machine also needs settings to allow DNS queries from Tailscale CGNAT.

# Run on DNS server side
sudo ufw allow from 100.64.0.0/10 to any port 53 proto tcp comment "DNS TCP from Tailscale"
sudo ufw allow from 100.64.0.0/10 to any port 53 proto udp comment "DNS UDP from Tailscale"

5. Verification Procedures

5.1 Server-Side Verification

# 1. Container startup verification
sudo docker ps | grep tailscale
# Expected: tailscale container in Up state

# 2. Tailscale authentication verification
sudo docker exec tailscale tailscale status
# Expected: home-router displayed with 192.168.x.0/24 in Routes

# 3. IP forwarding verification
sysctl net.ipv4.ip_forward
# Expected: net.ipv4.ip_forward = 1

# 4. Health check
curl http://localhost:9002/healthz
# Expected: 200 OK

5.2 Client-Side Verification

# 1. Tailscale connection verification
tailscale status
# Expected: Connection successful, 100.x.x.x IP obtained

# 2. LAN connectivity verification
ping 192.168.x.10
# Expected: Response received

# 3. DNS verification (Split DNS)
dig grafana.example.local
# Expected: Returns internal IP like 192.168.x.10

# 4. Service access
curl https://grafana.example.local/
# Expected: Normal response

5.3 Security Verification

# Inter-terminal communication blocking verification (from Admin device to Family device)
ping 100.x.x.x  # Tailscale IP of Family device
# Expected: Timeout (communication not possible)

6. Additional Notes

6.1 Important Settings Not Documented in Design Documents

Important configuration items discovered during actual construction that were missing from documentation:

6.1.1 DNS Server UFW Rules

Problem: DNS queries timeout even with Split DNS configured
Cause: DNS server UFW was blocking queries from Tailscale CGNAT (100.64.0.0/10)
Solution: Add the following to DNS server UFW

sudo ufw allow from 100.64.0.0/10 to any port 53 proto tcp
sudo ufw allow from 100.64.0.0/10 to any port 53 proto udp

6.1.2 DOCKER-USER Chain Configuration

Problem: ping works but DNS (UDP port 53) times out
Cause: DROP rules in DOCKER-USER chain were dropping UDP packets from Tailscale

-A DOCKER-USER -j DROP -p udp --dport 0:32767 -d 192.168.0.0/16

Solution: Add the following to /etc/ufw/after.rules

-A DOCKER-USER -j RETURN -s 100.64.0.0/10

6.1.3 UFW Routed Policy

Problem: Tailscale connects but all communication to LAN times out
Cause: UFW routed policy was deny by default, blocking packet forwarding
Solution: Change to DEFAULT_FORWARD_POLICY="ACCEPT" in /etc/default/ufw

6.2 Troubleshooting

When Split DNS Does Not Work

Check client settings
- iOS/Android: Check if Use Tailscale DNS is enabled in Tailscale app settings
- macOS/Windows: Check for conflicts between system DNS settings and Tailscale settings
Check Admin Console settings
- Is Restrict to domain correctly configured?
- Is Override local DNS Off?
Check with packet capture

   # Run on Subnet Router side
   sudo tcpdump -i any -n 'port 53'

When ping Works But Cannot Access Specific Services

Check DOCKER-USER chain

   sudo iptables -L DOCKER-USER -v -n

Check if RETURN rule for 100.64.0.0/10 exists

Auth Key Expiration

Since state is maintained with Named Volume, this is usually not a problem. However, a new Auth Key is required in the following cases:

When Named Volume is deleted
When device is deleted from Tailscale Admin Console

6.3 Operational Notes

Auth Key Rotation

Scenario	Required Action
Container restart	None (state is persisted)
Named Volume deletion	Issue new Auth Key, restart container
Device deletion from Admin Console	Issue new Auth Key, restart container

Version Update Procedure

Check Tailscale Release Notes
Verify new version in test environment
Update image tag in docker-compose.yml
docker compose pull && docker compose up -d

6.4 Reference Links

This completes the Tailscale Subnet Router construction. You can now securely access your home LAN from outside.

Obsidian AI Exporter: The Current Evolution Supporting Multiple AIs

Takashi Abe — Fri, 20 Mar 2026 01:51:03 +0000

Opportunities to interact with generative AI like Gemini and Claude in daily life have been increasing. When doing research or brainstorming, you often find brilliant ideas that make you go "aha!" during exchanges with AI, right?

But the moment you close your browser tab, those precious conversations flow away into the depths of your history. I wanted to keep my dialogues with AI as my own "knowledge asset" that I could search and link to. With that thought in mind, I released the Chrome extension "Obsidian AI Exporter" two months ago.

Thanks to everyone, many people have started using it, and over these two months I have received bug reports and feature requests and have made various updates. Today, I want to share with you the new features of this greatly evolved extension.

What Kind of Tool Is This?

Obsidian AI Exporter is an extension that extracts conversations with AI in your browser with one click and saves them as clean Obsidian documents.

It originally started as Gemini-only, but since I personally use multiple AIs, it now supports all the generative AI services I use. These days, you don't have to stick to a single platform.

Three Major New Features Added

Over the two months since release, it has evolved to be more flexible and more convenient.

1. Expanded AI Platform Support

In addition to Gemini, it now supports major AI services, including Claude, ChatGPT, and Perplexity. No matter which AI you are conversing with, just press the "Sync" button that appears in the bottom right of the same screen to save your entire conversation or research results.

2. Support for Saving Methods Other Than Obsidian

Although it bears the name Obsidian, you no longer necessarily need to use Obsidian. By configuring the Markdown function from the settings screen, you have the option to download as a pure Markdown file to your computer or copy to clipboard and paste into another editor.

3. Appending to Existing Notes and Adding Unique Features

An append mode has been added to write only new conversations to existing notes. Furthermore, fine adjustments tailored to each AI's characteristics have been made, such as saving the report portion of Gemini's Deep Research and the collapsible display of web search results in Claude.

It also supports the LaTeX format, so formulas are properly recorded.

Keep Your Important Data in Your Own Hands

What this extension is committed to is balancing privacy and convenience. Without going through external servers, all processing is completed in your browser and local environment. SSL is supported, but Obsidian-side configuration is necessary.

The more AI becomes our excellent partner, the more the dialogues exchanged there should become irreplaceable assets. Before they fly away and disappear, try pulling them to your hands with one click.

I am placing links to the Chrome Web Store and GitHub below. I would be delighted if you could install it and try out how it works.

Chrome Web Store:

Obsidian AI Exporter - Chrome Web Store

Export AI conversations from Gemini, Claude, ChatGPT, and Perplexity to Obsidian via Local REST API

chromewebstore.google.com

sho7650 / obsidian-AI-exporter

Obsidian AI Exporter

Chrome Extension that exports AI conversations from Google Gemini, Claude AI, ChatGPT, and Perplexity to Obsidian via the Local REST API.

日本語版はこちら

Features

Multi-platform support: Export from Google Gemini, Claude AI, ChatGPT, and Perplexity
One-click export: Floating "Sync" button on supported AI pages
Multiple output options: Save to Obsidian, download as file, or copy to clipboard
Deep Research support: Export Gemini Deep Research and Claude Extended Thinking reports
Artifact support: Extract Claude Artifacts with inline citations and sources
Tool content support: Optionally include Claude's web search results and tool activity as collapsible [!ABSTRACT] callouts
Append mode: Only new messages are added to existing notes
Obsidian callouts: Formatted output with [!QUESTION] and [!NOTE] callouts
YAML frontmatter: Metadata including title, source, URL, dates, and tags
Auto-scroll: Automatically loads all messages in long Gemini conversations
Platform-based organization: Use {platform}…

View on GitHub

I plan to continue adding convenient features little by little. If you have impressions from trying it or requests for features you want, please feel free to leave a comment on a GitHub issue or note.

AI Era: The Power of Writing Meditation - Connecting with Notebooks

Takashi Abe — Wed, 11 Mar 2026 01:34:12 +0000

Lately, I have been feeling a bit overwhelmed by the evolution of AI.

My reliance on AI has made my desires unmanageable. I can immediately start on ideas I have and let troublesome tasks be handled automatically. I feel it is wonderful that getting advice has lowered the hurdle to taking the first step.

However, it is also true that when I pause to reflect, moments of feeling lost have increased, wondering what exactly I am doing all this for.

During such times when I am about to be swallowed by waves of information and ideas, what saves me is not a digital screen but an old-fashioned analog notebook.

I pour my heart into a blank notebook, reconnecting with my life and purpose. What should I be doing now? What should I be thinking about? Should I calm my mind and deal with the task at hand, or should I move toward a future vision? Above all, I need to make a decision about what not to do.

When it comes to these things, no matter how excellent an AI I ask, answers simply will not come back. Unless you are going to walk a life decided by AI, if there is a path you want to walk on your feet, you absolutely need time to open your notebook and deeply face yourself.

For me, this time of self-dialogue is similar to meditation.

Time spent at my desk endlessly writing out characters and time spent slowly running while letting my thoughts wander. Both are beloved moments that I cannot do without.

However, when thoughts are just circling in my head, working memory fills up, and I am driven by the urge to write them out somewhere. That is precisely why a notebook as a receptacle for thought is optimal.

You might think you cannot take notes while running.

That is certainly true, and I have not yet found a good way to record things while running. But I have come to interpret that ideas I have thoroughly thought through while running and still vividly remember when I get home are what is truly important to me right now.

I may forget trivial triggers, but essential things will surely remain in my heart. Believing that, I only note down the crystals that remain after finishing my run and connect them to the next step.

I sit at an empty desk, staring at my notebook, tirelessly crafting characters. I love this tranquil time.

We intentionally pause in a time of abundance and convenience. Writing characters in a notebook allows you to meditate and listen to your own heart's voice. Would you like to try it once as well? I highly recommend it.

Accelerating AI and the Courage to Pause: Reclaim Your Core Values Through Essential Thinking

Takashi Abe — Mon, 02 Mar 2026 05:57:02 +0000

Lately, I have been hearing the term "AI fatigue" everywhere.

Bold claims are flying around that AI will change the world and that conventional tools are no longer needed. However, behind all this, I feel that the amount of activity each of us needs to handle has actually increased to an abnormal degree.

When I look back on my past personal development experiences, the pace was much slower. For someone like me who does not code as a main profession, touching programs every day is not easy. Creating one class a day was enough, and as the term "weekend programmer" suggested, development was something that progressed little by little, taking time.

But now, with the help of AI, I have three coding projects running simultaneously. New features are added every day, and issues that come up can be resolved within the same day. This is a speed that my former self could never have imagined.

However, when I stop and reflect, I begin to wonder if this is really what I wanted to do.

I started using AI to save time and improve efficiency, but before I knew it, I was being chased by the outputs that AI keeps producing one after another. To keep up with AI, I have been forcing myself to do unnecessary things. As a result, many outputs have been produced, but my mind has been tossed around and exhausted by them. This is not the future I wished for.

When it comes to work, I have found a certain answer for how to engage with AI. My goal is not mere efficiency but improving quality. As long as I keep that in mind, AI functions as a very reliable partner.

The problem is how I spend my private time. Being driven by code that AI has written or analysis reports that AI has organized feels somehow wrong.

So I decided to return to the concept of essentialism. What is truly important to me? In which areas can I use AI to genuinely enhance my motivation and results? I need to reassess these things.

It is natural to take responsibility for what you have created, but you must not be crushed by that responsibility and lose sight of your original purpose. Being controlled by something you started as a pastime or hobby is putting the cart before the horse.

Therefore, to protect my own time, I established new rules.

First, I place what is essentially important to me at the center of my schedule. Then, for everything else that I could do but is not urgent, I confine it to specific time blocks.

Specifically, I dedicate my morning hours at the start of the day to my most mentally demanding important work and my core activities. I make sure to finish essential tasks within the morning. Then, I allocate tasks that do not require as much concentration and hobby-related activities to afternoon time blocks. If they do not get finished within that time, I simply carry them over to the next day.

In the past, being controlled by other people was a source of frustration, but now that may have simply transformed into being controlled by AI.

Precisely because I have obtained such a convenient tool, I want to have a clear sense of what I want to do and what I should do. Rather than matching myself to the speed of AI, I want to incorporate AI into my own comfortable rhythm. In this way, I intend to continue protecting my own way of moving forward.

When I Hired Multiple Generative AIs as Subordinates, Parallel Development Processing Never Stopped

Takashi Abe — Wed, 11 Feb 2026 15:00:00 +0000

Today is a relaxed introduction to recent Shossan updates.

1. Major Update to Obsidian AI Exporter

The tool I have been publicly releasing for saving Gemini chat results to Obsidian, called Obsidian AI Exporter, has been significantly powered up.

In my previous introduction, it was Gemini-only, but now it supports four sites: ChatGPT, Claude (including Deep Research), and Perplexity. In addition to Obsidian integration, you can now save as pure Markdown files or copy to clipboard.

Obsidian AI Exporter - Chrome Web Store
Export AI conversations from Gemini, Claude, ChatGPT, and Perplexity to Obsidian

While I think it will be in the maintenance phase unless there are major UI changes, I am still looking to add more useful features. If you have any feature requests, please let me know!

Currently, I am considering automatic tagging, expanding the append feature, which is still not quite there, and Wiki Link support for Obsidian.

2. Building Your Own News Curation Site with n8n

I wanted a site where I could read the latest overseas news summarized in a format convenient for me, so I developed my own curation platform.

The mechanism uses n8n to fetch updates from specific RSS feeds and URL lists, then an LLM (generative AI) translates and summarizes the content into Japanese. This is then registered to a display app I built with Docker.

By managing specific news URLs as unique keys, it prevents duplicate posts with a simple mechanism. The main body is simple and just displays content, but I designed it with loose coupling so that LLMs and feeds can be easily changed. I have also published the source code, so please take a look if you are interested.

Around v2, the check/ingest/post article parts are the developed app portions.

I named it tech-news as is since it is for personal use, but really the content to post can be anything as long as it is Markdown, so it is like a simple blog. Since I am developing it component by component for easy reuse, I am feeling like it has become more versatile than I expected.

3. Revamping Home VPN Environment with Tailscale

On the infrastructure side, I am organizing my home access environment.

Tailscale | Secure Connectivity for AI, IoT & Multi-Cloud
The connectivity platform for devs, IT, and security teams.

I had been using the VPN function of my Yamaha router, but considering security and convenience, I am currently introducing and configuring Tailscale.

Being able to safely access home resources via NAT traversal without opening VPN ports externally is safe and comfortable. The app is also easy to use, and functionally very detailed settings are possible. I have no idea why it is free for up to 3 users.

Currently, I am configuring a router with Docker on my home Linux server and managing settings with Ansible. An environment is coming together where I can work without being conscious of the boundary between home and the internet even when out.

From the Joy of Researching to the Joy of Realizing

Running multiple projects in parallel like this, I can feel the changes in development style in the AI era firsthand.

In the past, I found joy in the trial and error of researching technologies one by one. But now, I find it fun to watch my ideas take shape one after another, using multiple generative AIs as my subordinates. Is this a change due to age, or is it new excitement brought about by technological evolution?

The image of what I wanted to do becomes realized with the help of AI. Grinning at that process, I am giving instructions to my new subordinates again today.

How to Transform 3 Years of Thinking into Assets: Accelerate Feedback with Claude Cowork

Takashi Abe — Wed, 11 Feb 2026 13:30:16 +0000

Claude Cowork: The Ultimate Engine for Objectively Viewing Your Own Thought Evolution

I had been pondering whether Claude Cowork actually has any practical uses.

Then I discovered yet another new way to use it. Cowork is a work companion that autonomously executes multiple tasks based on massive amounts of data that surpass what chat can handle.

Claude Cowork: The Ultimate Engine for Objectively Viewing Your Own Thought Evolution

As you know, Claude Cowork is not merely a chat tool. It is an AI agent that directly accesses your local file system (in my case, Obsidian) and autonomously completes tasks.

You can either place Obsidian in a folder that Cowork can access, or use the combination of Local REST API + Obsidian MCP Tools to have Cowork retrieve information via MCP—both approaches work effectively.

What makes this tool truly disruptive is its ability to execute against three years of my living thought data with precision and speed comparable to the Observe and Orient phases of the OODA loop (Observe, Orient, Decide, Act). Sounds pretentious, right?

Enabling High-Dimensional Differential Extraction Across Time—Something Difficult to Do Alone

Why bother using Claude Cowork? Because I know how vague human memory is and how conveniently it gets rewritten.

Breaking Through the Limits of Observe: It is humanly impossible to extract every single description on a specific theme from three years of notes numbering in the thousands. Information obtained through word searches is only a fraction. You need to extract information while considering intent as well. Cowork autonomously repeats searching and browsing, comprehensively observing all data.

Deepening Orient: The thinking habits of my three-years-ago self versus my current self, the subjects of interest, and changes in word choice. By having AI identify these differences, I can confront my own growth or stagnation as objective facts that I could never have noticed on my own.

This is not for reminiscing about the past, but for gaining an advanced metacognitive environment to use my past self as a stepping stone toward new ideas.

This is an effective environment that I could not achieve simply by using Obsidian as RAG with Dify. What was limited to merely retrieving information has now evolved into comprehensive information retrieval and analysis.

Using Three Years of Obsidian as Fuel to Gain Insights for the Future

I have actually shared my three years of Obsidian data with Claude Cowork and am running workflows like the following:

Step 1 (Observe): Scan all notes containing my views on generative AI from 2023 to the present (2026).

Step 2 (Orient): Analyze chronologically at which points and through which technological breakthroughs my thinking changed.

Step 3 (Insight): From that trajectory of change, have it present blind spots in thinking that I should focus on in the next year.

[Image of spinning the OOA loop with Cowork]

Previously, doing this required spending several days reading through past notes. However, with Claude Cowork, while generating intermediate analysis files in the working folder, it writes up a map of my own thinking in just minutes. This is not mere summarization—it is prototyping for the future through dialogue with my past self.

This is an efficient and effective way to reuse PKM (Personal Knowledge Management).

Continuously Updating Your Thinking Together with an AI Colleague

In these uncertain times ahead, there is no time to cling to past success stories. On the other hand, data about what you thought in the past and how you experimented is your own unique asset that belongs to no one else.

Stop using Claude Cowork as just a summarization tool.

Cowork is literally a partner for increasing the speed of your thinking and running the OODA loop faster than anyone else. Whether you let three years of data sleep as mere records or turn it into a power plant for your next ideas—that key depends on how you master Cowork as an agent.

I will continue to gaze into this abyss of the ultimate mirror and refine my thinking day after day.

The Illusion of My Own Efficiency: How Claude Exposed My Arrogance and Lack of Planning at Night

Takashi Abe — Fri, 06 Feb 2026 07:21:29 +0000

Conversations with AI are not for improving skills, but for recognizing your own arrogance

I, Shossan, have a certain pride in having automated my environment reasonably well and controlling it efficiently. However, through analyzing my own shell history while conversing with the trending Claude Cowork, what was thrust before me was an image of myself—utterly unplanned and full of biases. How embarrassing.

Being prompted by AI to improve is a shock close to defeat as an engineer. However, I am convinced that this very defeat is the only gateway to the next stage of growth. Gemini's words are too harsh.

People mistake unconscious repetition for effort

Why couldn't I notice my own inefficiencies? It's because a bias called familiarity had crept into my daily work.

This time, when I had Claude cowork analyze my past command history, the following three blind spots were exposed:

Collapse of time management: Activity peaked at 21:00, a time when I should have been resting. This wasn't diligence—it was merely repaying debt caused by lack of planning during the day.

Hollow automation: I manually executed ansible-playbook 31 times. While thinking I was using automation tools, the execution process itself was extremely analog and dependent on manual work.

Tool dependency: By using convenient tools (Keyboard Maestro, Stream Deck, Claude Code, etc.), I had arbitrarily decided that there was no more room for improvement.

The cold data-driven insights and the automation functions I immediately implemented

According to Claude's analysis, my activity is concentrated at 8:00 and 21:00. The fact that I was hammering away at commands at 21:00 after my bath is evidence of a bad habit that degrades sleep quality and diminishes the next day's performance. I truly never expected such results. I was genuinely surprised.

You should sleep after your bath. If you have to execute commands at that time, it means your planning has failed. Accepting this fact, I immediately adopted the improvement proposals that Claude suggested.

For example, here is a function for managing my custom LaunchAgents that start with com.oshiire.. Until now, I had been typing commands while trying to remember paths or searching through history, but now this svc function takes over that cognitive load.

# ~/.config/fish/functions/svc.fish
function svc --description "LaunchAgent service control"
  set -l action $argv[1]
  set -l name $argv[2]
  set -l plist ~/Library/LaunchAgents/com.oshiire.$name.plist

  switch $action
    case start
      launchctl load -w $plist
    case stop
      launchctl unload -w $plist
    case restart
      launchctl unload -w $plist; and launchctl load -w $plist
    case status
      launchctl list | grep $name
    case '*'
      echo "Usage: svc [start|stop|restart|status] [service_name]"
  end
end

Additionally, Claude proposed a short function called ap for ansible-playbook. This eliminates small decisions like argument specification mistakes and forgotten options. Such thoughtful consideration.

Looking into the mirror called AI, strategically updating yourself continuously

If you just end up praising AI's improvement suggestions as amazing, you are merely a consumer. For me, the learning from this experience lies in how to convert the negative of having AI point things out to me into the positive of solving through systems.

Abandon the assumption that you are doing well, and set aside time to regularly dissect yourself with objective data. Use AI not just as a code generator but as a behavioral analysis partner.

From here, I will continue to cut away waste, one step at a time. Why don't you also try exposing your terminal history and behavioral history—your embarrassing parts—to AI?