DEV Community: sunah kim

Twig 3.30 Broke Every Page of EC-CUBE with a 500 — Blame the Return Types Added in 3.12

sunah kim — Thu, 29 Oct 2026 11:58:19 +0000

Introduction

While running composer audit on a production EC-CUBE 4.3 site, I found a security advisory against twig/twig. "Just bump it to the patched version" — so I updated Twig from the 3.8 line to 3.30 and deployed to the dev environment. Every single page returned 500.

Why does a minor update within the same 3.x line break things this badly? The cause was the return types Twig added to its abstract methods in 3.12.0. This post is a record of the investigation, the 6-line fix, and the verification.

What happened — 500s everywhere and a Fatal error

Right after the deploy, every URL returned 500. The PHP error log showed:

PHP Fatal error:  Declaration of Eccube\Twig\Template::getTemplateName()
must be compatible with Twig\Template::getTemplateName(): string

EC-CUBE 4.3 ships its own Eccube\Twig\Template class that extends \Twig\Template, and PHP was complaining that the override is no longer "compatible" with the parent.

The cause — return types on abstract methods in Twig 3.12.0

In 3.12.0, Twig added return types to five abstract methods of its Template class:

Method	Declaration since 3.12.0
`getTemplateName()`	`: string`
`getDebugInfo()`	`: array`
`getSourceContext()`	`: Source`
`doDisplay()`	`: iterable`
`display()`	`: void`

In PHP, once a parent method declares a return type, every override must declare a compatible (covariant) return type. Having no return type does not count as compatible. The moment the parent gains a type, every untyped subclass turns into a Fatal error.

To pinpoint which version introduced the change, I compared src/Template.php across tags using GitHub raw:

for v in v3.9.0 v3.11.0 v3.12.0; do
  echo "== $v =="
  curl -s "https://raw.githubusercontent.com/twigphp/Twig/$v/src/Template.php" \
    | grep -E 'abstract .*function|function (getTemplateName|getDebugInfo|getSourceContext|doDisplay|display)\('
done

No types up to v3.11.0; types from v3.12.0. That's the boundary.

The tricky part is on the EC-CUBE side: neither 4.3.0 nor 4.3.1 has return types on this class. The composer.json declares twig/twig: ^3.8, yet in practice it only runs on 3.11 or below. The fix only landed in 4.4.0-alpha-1.

The fix — add return types to 5 overrides (6 lines)

Flip that around and the "answer" already exists in the corresponding file of 4.4.0-alpha-1. I backported it to 4.3 by adding return types to the five overrides in Eccube\Twig\Template:

-    public function getTemplateName()
+    public function getTemplateName(): string

-    public function getDebugInfo()
+    public function getDebugInfo(): array

-    public function getSourceContext()
+    public function getSourceContext(): \Twig\Source

-    protected function doDisplay(array $context, array $blocks = [])
+    protected function doDisplay(array $context, array $blocks = []): array
     {
+        return [];
     }

-    public function display(array $context, array $blocks = [])
+    public function display(array $context, array $blocks = []): void

Two points worth noting:

The parent declares doDisplay(): iterable, so I declared the override as : array — a covariant subtype — and added return []; (the method never returned anything before).
I wanted to add the #[\Override] attribute too, but that's a PHP 8.3 feature and the server runs PHP 8.2, so I skipped it this time.

Verification and rollback plan

The fix is 6 lines, but it's a production site, so verification went step by step:

Syntax check with php -l
Deploy to dev, then bin/console cache:clear → cache:warmup
curl the 8 main pages — all 200
bin/console lint:twig — all 258 templates OK
Confirm 0 ERROR lines in the site log
Confirm composer audit now reports 0 advisories

I also prepared the rollback path up front: keep a full backup of the pre-update vendor/ directory, and restoring is just a mv swap — about 40 seconds measured. Knowing you can go back makes applying changes to production far less stressful.

Takeaways

Changing an abstract method's signature is a BC break in semver terms, and Twig did exactly that in 3.12. "Same 3.x, so it's safe" stops being true the moment you inherit from a framework class.
Keep a list of which upstream abstract methods your codebase overrides. Those are the candidate breakage points for the next update.
Look at the corresponding file in the upstream's next major release (even an alpha) — the fix you need to backport is often already written there. In this case, 4.4.0-alpha-1 was the answer.

The real takeaway for me: I now have one concrete answer to "I only bumped within 3.x — why did it break?"

The 3 Principles of Harness Engineering — Map, Enforce, Accumulate

sunah kim — Sat, 24 Oct 2026 11:59:56 +0000

Introduction

Recently I wrote about setting up a harness (CLAUDE.md / Hooks / Skills) for Claude Code in my side-project app:

https://zenn.dev/pythona/articles/claude-code-harness-first-setup

That post was a hands-on record of what I built. This time I want to step back and organize the underlying idea — the three principles of harness engineering — as a mapping table: which Claude Code feature is responsible for which principle. The principles themselves come from an article by OpenAI; I learned about them through a Japanese summary page (linked under "References" at the end).

Note: I was only able to read the first part of the reference page (the principles table, the prompt structure, and the beginning of the CLAUDE.md guide). My interpretation here is partly filled in from my own practice.

Mapping the 3 principles to Claude Code features

Principle	In one line	Claude Code feature
① Hand over a map, not a manual	Teach the big picture and where to look, nothing more	CLAUDE.md (+ docs/)
② Enforce invariants, don't dictate implementation	Mechanically guard only the rules whose violation is an incident	Hooks
③ Codify missing capabilities	Turn every failed procedure into an asset	Skills

Reduced to these three lines, it becomes clear that each plays a completely different role. Let's go through them.

① The map — CLAUDE.md as a signpost under 200 lines

The temptation is to hand over the whole manual. But a long manual eats context, and the most important lines are exactly the ones that get skipped. The map principle says: keep CLAUDE.md a signpost under 200 lines, push the details out into docs/, and let the agent follow links when it needs them.

The recommended structure is five sections, with the project overview first:

# CLAUDE.md (skeleton)
## 1. Project overview   <- always goes first
## 2. Tech stack & common commands
## 3. Invariants (violations get blocked by Hooks)
## 4. Recommended conventions (recoverable if broken)
## 5. Where to Look (details live in docs/)

In my own project, following this policy got CLAUDE.md down to 48 lines. The default move becomes "evict to docs/" rather than "add another line".

② Enforcement — don't mix "please" with invariants

Natural-language instructions are, at bottom, all "please" — they are followed probabilistically. Meanwhile, accidents like reading .env or directly editing native directories are unacceptable even once.

So this principle says: mechanically block only the things whose violation is an incident, using a PreToolUse Hook (exit 2), and leave everything else as "recommended" in CLAUDE.md. The other direction matters just as much: don't use Hooks and rules to pin down how to implement things. Over-constrain the means and you block off the model's own toolbox of solutions. Guard the conditions; delegate the implementation.

The concrete Hook setup and how I tested it are in my previous post, so I'll defer to that.

③ Accumulation — Skills grow one per failure

The third principle is the least flashy and the most effective. Every time something fails, write the correct procedure down as a Skill. From then on, you just invoke it and never trip over the same step again.

---
name: new-screen
description: Steps for adding a new screen
---
1. Create the expo-router route file under app/
2. Put the screen component under components/screens/
3. Run type checks and tests after adding it

Each one is a small memo, but the longer the project runs, the more "handrails appear exactly where you fell", so the effect compounds.

Workflow in practice: build the harness before the app

Once the mapping table is in your head, the opening move of a new project changes. My first prompt now generates the harness structure, not the app itself:

Set up a Claude Code harness for this repository.
1. CLAUDE.md (under 200 lines, 5 sections, project overview first)
2. PreToolUse hooks under .claude/hooks/ that guard invariants (e.g. protect .env)
3. Skill skeletons for /commit and /review under .claude/skills/
Split detailed documentation into docs/.

When moving on to app implementation, I state the design and verification conditions up front: e.g. "monotone color scheme", "no emoji as decoration", "after implementing, always run the lint → type check → test verification loop". Handing these over as initial conditions is far faster than going back and forth later with "this looks AI-generated, please fix it". Assets and layout tweaks, on the other hand, I treat as something that won't land in one shot — those get refined through iterative instructions.

Summary

Map (CLAUDE.md): a signpost under 200 lines. Evict details to docs/ and let the agent follow links
Enforce (Hooks): mechanically block only the invariants whose violation is an incident. Don't constrain how to implement
Accumulate (Skills): document the procedure every time something fails. The effect compounds

Thinking in these three layers — map, enforce, accumulate — you get a development environment that stops repeating the same mistakes through structure, not through prompt-writing skill. Before polishing the prompt, suspect the harness. That's the order I think in these days.

References

Japanese summary page on Claude Code and harness engineering (Notion)

Setting Up a Harness for Claude Code: Enforce Invariants with Hooks, Not Prompts

sunah kim — Fri, 23 Oct 2026 11:55:06 +0000

Tired of writing the same warnings every time

I've been using Claude Code on FitLog, a personal workout-tracking app built with Expo / Supabase / Zustand / NativeWind / React Native Reusables. After a while I noticed the same mistakes kept happening:

It would casually read .env
It tried to edit ios/ and android/ directly, even though Expo manages them
It modified the original components/ui/ files generated by Reusables

Each time, I added another "please don't do X" to my prompts. The warnings kept piling up, but whether they were followed was basically luck. The longer the instructions got, the more the important parts got buried.

Around that time, OpenAI published a piece on "harness engineering" that was making the rounds, so I took the opportunity to set up a proper harness for the project from scratch.

To be honest: the original page returned a 403 and I couldn't read it. This article is not a commentary on the original — it's a record of applying three principles I picked up from summaries:

Give the agent a map, not a manual

Enforce invariants; don't dictate implementation

Disclose details progressively, when needed

The cause: every rule was a "please"

Looking back, the problem was how the rules were written. "Things that must never happen" and "things I'd prefer" sat side by side in my prompts and CLAUDE.md, written in exactly the same tone.

Natural-language instructions to an LLM are all, fundamentally, requests. As the context grows, some get skipped. But an accident like reading .env is game over even if it happens once. I had been placing rules that needed deterministic enforcement in a place where compliance was probabilistic.

Following "enforce invariants, don't dictate implementation," I sorted the rules into two buckets:

Category	Examples	Where it lives
Invariants (breaking them = incident)	Accessing `.env*`, hand-editing `ios/`/`android/`, modifying `components/ui/` originals	Mechanically blocked by hooks
Recommendations (breaking them = fixable)	Naming conventions, directory layout, commit granularity	Listed as "recommended" in CLAUDE.md

The fix: a 48-line map + 4 hooks + 5 skills

Keep CLAUDE.md down to a 48-line "map"

CLAUDE.md now contains only the stack, common commands, the list of invariants, and a "where to look" table — everything else is a link into docs/. It ended up at 48 lines.

## Where to Look
| What you need | Where |
|---|---|
| Screens & navigation | docs/architecture.md |
| DB schema & RLS | docs/db-schema.md |
| How to use UI components | docs/reusables-guide.md |
| Naming & coding conventions | docs/conventions.md |
| Hooks & skills, and why they exist | docs/harness.md |

docs/ has six files: architecture / db-schema / reusables-guide / conventions / harness / design-docs. Instead of making the agent read everything every time, the structure lets it navigate there when needed — my attempt at progressive disclosure.

Enforce invariants with PreToolUse hooks and exit 2

I wrote four hooks: protect-env, protect-native, format (silently skips if Prettier isn't installed), and a Stop hook that summarizes git diff --stat as a system message.

The core one, protect-env, looks like this (excerpt):

#!/bin/bash
# .claude/hooks/protect-env.sh
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // .tool_input.file_path // ""')

# .env.example is allowed
if echo "$cmd" | grep -qE '\.env\.example'; then exit 0; fi

if echo "$cmd" | grep -qE '(^|[ /"'"'"'])\.env(\.|[ "'"'"']|$)'; then
  echo "BLOCKED: access to .env* is forbidden." >&2
  echo "For variable names, see .env.example instead." >&2
  exit 2
fi
exit 0

The key point: don't just stop with exit 2 — use stderr to tell the agent what to do instead. protect-native suggests "use an Expo Config Plugin instead of editing ios/ directly"; the Reusables guard says "wrap the component instead of changing the original." A blocked Claude picks its next action, so showing it a way forward gets it back on track faster.

Patterns that leak through staging rather than reading — like git add .env — are caught by the same hook.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Read|Edit|Write",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/protect-env.sh" },
          { "type": "command", "command": ".claude/hooks/protect-native.sh" }
        ]
      }
    ]
  }
}

A hook you haven't tested is a hook you can't trust, so I prepared ten sample JSON inputs (six that should block, four that should pass) and verified the exit codes directly in the shell:

$ ./test-hooks.sh
[BLOCK] cat .env                          -> exit 2 OK
[BLOCK] git add .env                      -> exit 2 OK
[ALLOW] cat .env.example                  -> exit 0 OK
[ALLOW] ls src/components                 -> exit 0 OK
...
10/10 passed

Vary how skills are invoked by blast radius

Five skills: /commit, /review, /deploy, /cleanup, /new-screen. /commit encodes the commit-message conventions (Korean, no trailing period, type: description format, git add . forbidden). /deploy encodes "EAS preview build only after tests and tsc pass."

Anything with a large blast radius, like deploys, gets disable-model-invocation: true so the model can't call it autonomously — it's user-invocation only.

What went wrong, and what's still unverified

Couldn't read the original. The 403 meant I designed from summaries. Not pretending to know what you haven't read applies to blog posts and to AI work alike.
Claude guess-interpreted a broken README. During setup, it filled in a README full of typos and truncated sentences with "it probably means this" and kept going. If the map itself is broken, a harness won't prevent misreading.
Hooks untested in a real session. The standalone tests passed 10/10, but I haven't yet confirmed they fire as intended mid-session.

Takeaways

Keep CLAUDE.md a short map; push details into docs/ and let the agent follow links
Split rules into "enforced" vs. "delegated." Only incident-grade rules get a hook with exit 2; everything else stays a recommendation
When you block, use stderr to point at the alternative — recovery is faster
Test hooks against sample inputs and check exit codes before relying on them
Don't start with hooks for everything; promote a rule to a hook only after the same mistake repeats

Rather than stacking up more "pleases," guard the few places where a breach would actually hurt — mechanically. That trade-off alone made my prompts shorter and a lot quieter.

Open Any Finder Folder in VS Code with One Keystroke (Automator Quick Action)

sunah kim — Thu, 22 Oct 2026 11:56:25 +0000

Dragging folders gets old fast

When you're browsing a project folder in Finder and think "I want this open in VS Code" — what do you do?

For a long time, I would launch VS Code first and then drag the folder onto the Dock icon or the window. Or open a terminal, cd into the folder, and run code .. Either way it's only a few seconds, but repeated many times a day it adds up. It feels especially tedious when you just want to peek at the contents.

With macOS's built-in Automator, you can create a "Quick Action" once, and from then on it's: select the folder in Finder → right-click (or press a shortcut key) → VS Code opens instantly. Setup takes five minutes. Here's the procedure, plus the one detail that matters.

Creating the Quick Action in Automator

1. Create a new Quick Action

Launch Automator.app and choose "Quick Action" as the new document type.

2. Configure how input is received

Change the settings at the top of the workflow as follows. If you get this wrong, the action won't appear in Finder's right-click menu at all:

"Workflow receives current" → folders
"in" → Finder.app

3. Add "Run Shell Script"

Drag "Run Shell Script" from the action list on the left into the workflow, and configure it:

Shell: /bin/zsh (bash works too)
Pass input: "as arguments" (if you leave the default "to stdin", "$@" will be empty)

The script itself is just this:

for f in "$@"; do
  open -a "Visual Studio Code" "$f"
done

The loop is there so that selecting multiple folders opens each one in its own window.

4. Save

Press ⌘S and give it a name. I went with "Open in VS Code" — this name is exactly what shows up in the context menu.

Now you can right-click any folder in Finder → "Quick Actions" → "Open in VS Code".

Assigning a keyboard shortcut

If you want to skip even the right-click:

System Settings → Keyboard → Keyboard Shortcuts
Open "Services" → "Files and Folders" on the left
Find your saved "Open in VS Code" action and assign a shortcut (I used ⌃⌥V)

Select a folder in Finder, press the key, and VS Code opens. Once you have this, there's no going back to dragging.

The key point: use `open -a`, not the `code` command

It's tempting to write the script as code "$f", but using open -a is the whole point of this setup. Two reasons:

1. You sidestep the PATH problem. The code command only exists after you run "Shell Command: Install 'code' command in PATH" from the VS Code command palette. Worse, Automator's shell runs without loading .zshrc, so your interactive shell's PATH settings don't apply. In other words, even if code works fine in your terminal, inside Automator it tends to fail with command not found. Meanwhile, open -a is a standard macOS command that works from anywhere as long as the application name is correct.

2. It's portable with zero setup. With open -a, the same Quick Action works on your teammates' Macs as long as VS Code is installed. No "please enable the code command first" prerequisite — a small but real win.

Note that the app name must match the official name in your Applications folder. If you use VS Code Insiders, it's "Visual Studio Code - Insiders". A mismatched name fails with an Unable to find application error.

Summary

Automator's Quick Actions let you go from a Finder right-click straight to VS Code
Input must be "folders" / "Finder.app", passed "as arguments" — get these wrong and nothing works
The script is open -a "Visual Studio Code" "$f"; unlike the code command, it needs no PATH setup
Assign a key in System Settings → Keyboard Shortcuts → Services to shrink it down to a single keystroke

This is the kind of setup you build once and use until you switch operating systems. If you're still dragging folders every time, it's worth the five-minute investment.

Reference

How to open a Finder folder directly in VS Code on Mac (Korean)

The Clipped Dropdown in a Collapsed Sidebar — the Hidden Meaning of overflow-y: auto

sunah kim — Wed, 21 Oct 2026 11:55:28 +0000

The QA report

"When the sidebar is collapsed, the '+ Create' menu gets cut off."

The screenshot showed exactly that: with the sidebar collapsed to 60px, the dropdown menu was sliced clean off at the sidebar's right border. Only the first character of "New folder" was visible.

The strange part: with the sidebar expanded (244px), the same menu rendered fine. Same code, same 190px menu width. It only broke when collapsed.

Where I got stuck

My first suspect was z-index — maybe the menu was hiding under something. But DevTools showed the menu was in the DOM with a plenty-high z-index. It wasn't hidden; it was being physically clipped at the sidebar's boundary.

Next suspect: overflow. But all the sidebar had was this:

.sidebar {
  width: 60px; /* collapsed; 244px when expanded */
  overflow-y: auto; /* vertical scroll for long item lists */
}

No overflow-x anywhere. "The horizontal axis is still visible, so anything sticking out should show" — or so I thought.

The cause: one non-visible axis drags the other along

The CSS spec has this rule:

When one of overflow-x / overflow-y is set to something other than visible, a visible value on the other axis computes to auto.

So the moment you write overflow-y: auto, the unspecified overflow-x silently becomes auto. Sure enough, the Computed tab in DevTools showed overflow-x: auto.

Now everything added up:

The menu was floated inside the sidebar with position: absolute
The sidebar was effectively an overflow: auto auto scroll container
A 190px menu inside a 60px container → the horizontal overflow gets clipped (or scrolled)

It had survived in the expanded state only because 244px happened to fit most of the menu, so the clipping wasn't noticeable. Structurally, it was doomed to clip from day one.

The fix: `position: fixed` only while collapsed

I couldn't drop overflow-y: auto — the scroll is needed. So instead, while collapsed, the menu escapes the scroll container's coordinate system. position: fixed positions against the viewport, so ancestor overflow can't clip it (caveat: an ancestor with transform etc. changes the containing block).

The position comes from the button's getBoundingClientRect(). In React, I store the coordinates in state on click and feed them into style:

const [menuPos, setMenuPos] = useState<{ top: number; left: number } | null>(null);

const handleOpen = (e: React.MouseEvent<HTMLButtonElement>) => {
  if (collapsed) {
    const rect = e.currentTarget.getBoundingClientRect();
    // float it just to the right of the button
    setMenuPos({ top: rect.top, left: rect.right + 8 });
  }
  setOpen(true);
};

<ul
  className={collapsed ? "menu menu--fixed" : "menu menu--absolute"}
  style={collapsed && menuPos ? { top: menuPos.top, left: menuPos.left } : undefined}
>

.menu--absolute {
  position: absolute; /* expanded: as before */
  top: 100%;
  left: 0;
}
.menu--fixed {
  position: fixed; /* collapsed: escape the sidebar */
}

I kept the expanded state on the old absolute path. Moving everything to fixed was tempting, but the expanded state has existing scroll-following behavior tangled in, so I limited the blast radius to the collapsed state.

To verify, I opened the menu in the collapsed state on a local build and compared rectangles in the console:

const menu = document.querySelector(".menu--fixed").getBoundingClientRect();
const sidebar = document.querySelector(".sidebar").getBoundingClientRect();
console.log(menu.left >= sidebar.right); // true → the menu is outside the sidebar
console.log(menu.right, document.documentElement.clientWidth); // still within the viewport?

menu.left sat to the right of the sidebar's edge and the whole menu fit in the viewport. Done.

Takeaways

Two lessons from this one.

1. A popover inside a scroll container will eventually get clipped.
The instant you write overflow-y: auto, that element becomes a container that clips horizontally too. Any dropdown or tooltip floated inside it with absolute gets cut the moment it outgrows the container. "It looks fine now" just means it happens to fit today. Put popovers on fixed or in a Portal — outside the scroll container — from the start.

2. Auxiliary states like "collapsed" deserve one pass per feature.
That same day we got three bug reports tied to the collapsed state: a drawer opening as a 60px sliver, the hamburger icon showing at desktop width, and this clipped menu. All of them worked perfectly when expanded and broke the moment you collapsed. We had only ever tested the default state. Of all the state combinations (expanded × collapsed, light × dark, desktop × mobile), the side you don't personally use is exactly the one worth a full lap.

Hope this saves someone the same detour.

Permissions Hadn't Changed, but QA Said 'I Can't Create' — Answering with a Table Uncovered an Unreachable Branch

sunah kim — Sun, 18 Oct 2026 11:53:29 +0000

The question

QA for our internal business system sent me this:

I can't create a project. Did it change so that only executives can create them now?

Short answer: no, the permission rules hadn't changed at all. But the question turned out to be valuable. While building a permission table to answer it, I cross-checked the code — and found a branch that could never execute. Dead code, alive in production. Here's how it happened.

Background: we had just changed how roles are stored

Shortly before this, we changed how job roles are modeled.

Before: one role per user
After: one role per affiliation (seat) — to support concurrent posts and secondments, a user can hold multiple affiliations, each with its own role

The project-creation rules themselves were untouched:

Role	Can create projects in
Chairman / Secretary	Entire group
President / Executive	Own company
Department head / Section chief / Team leader	Own org and below
Team member	Nowhere

The "did the system change?" question almost certainly came because of that recent refactor. When a system is being actively changed, every unrelated symptom starts looking like a side effect of "that change."

Trying to answer with a table, I read the code

I could have just replied "nothing changed," but for permission questions, a table is the most reliable answer. To build the table above, I re-read the actual check:

Scope scopeOf(long userSeq, Role role) {
    if (role == CHAIRMAN || role == SECRETARY) return companyWide();
    if (role == PRESIDENT || role == EXECUTIVE) return ownCompany();
    if (role == TEAM_MEMBER) return denied();  // ← early return

    // Per-affiliation branch (added in the refactor):
    // even if the primary affiliation is "team member",
    // a section chief seat elsewhere can create under that org
    for (Affiliation a : affiliationsOf(userSeq)) {
        if (a.role().isLeaderOrAbove()) {
            return orgScope(a.org());
        }
    }
    return denied();
}

See it? The for loop was added during the per-affiliation refactor, precisely to handle "primary affiliation is team member, but section chief somewhere else." But above it, the pre-refactor early return for TEAM_MEMBER was never removed.

Since the role argument carries the primary affiliation's role, any user whose primary role is team member hits return denied() on line 3 — and the loop below it never runs. The code we wrote for concurrent-post users had never executed, not even once.

The compiler can't warn you about this. Syntactically, both branches are reachable. Code written after a return statement triggers an unreachable-code error, but a branch that's unreachable because of how the conditions combine can only be found by a human reading the code — or by a test.

The fix: drop TEAM_MEMBER from the early return

The fix itself was small: stop short-circuiting on "team member," and read the affiliations before judging.

Scope scopeOf(long userSeq, Role role) {
    if (role == CHAIRMAN || role == SECRETARY) return companyWide();
    if (role == PRESIDENT || role == EXECUTIVE) return ownCompany();

    // If any seat is leader-or-above: that org and below. Otherwise: denied.
    for (Affiliation a : affiliationsOf(userSeq)) {
        if (a.role().isLeaderOrAbove()) {
            return orgScope(a.org());
        }
    }
    return denied();
}

I verified with a user whose primary affiliation is a team member but who holds a section-chief seat at another company:

the creation-scope API returns allowed: true with the section-chief org
a project-creation POST under that section returns 201
creation under the primary org still returns 403

One more thing: deployment timing. If the server restarts while QA is in the middle of testing exactly this permission area, they get confused by unrelated errors. I scheduled the release for 14:00, right after lunch break, so the restart landed between test sessions.

Answering QA

The answer to the original question was simple: "The permission rules haven't changed — here's who can create where," with the table attached. And for the cases where creation still fails, I asked three things:

which account, and that account's affiliations and roles
whether the create button is missing or clicking it errors out (and if so, the exact message)
which organization was selected as the creation target

A bare "it doesn't work" is unreproducible for permission bugs, so having these triage questions templated saves a lot of round trips.

Takeaways

When you add a branch below an early return, check that the branch is actually reachable. The compiler won't catch condition-level unreachability; only a human read or a test will. If we'd had a concurrent-post user in the test suite from day one, we'd have caught this at refactor time.
Answer permission questions with a table. Building the table forces you to re-read the implementation, and mismatches between the rules and the code — like this dead branch — surface along the way.
Schedule permission-related deploys outside QA's testing hours. A single restart at the wrong moment costs you trust.

A naive-sounding "did the system change?" ended up unearthing a latent bug. I'm grateful for the question.

Stamping a Company Seal on Excel Invoices: No Private Storage, a Lying resize(), and Three Coordinate Systems

sunah kim — Sat, 17 Oct 2026 11:54:23 +0000

The task

In our internal business system, I built a feature that stamps a company seal (the square kaku-in used on Japanese business documents) onto invoices, quotes, and purchase orders. The documents are Excel templates filled with data and converted to PDF via LibreOffice. The requirements:

Never distribute the seal image by itself — no public URL, no image-serving API. It may only be seen stamped on a document
Per-document ON/OFF toggle
Once a document is finalized, replacing the seal later must not change it — but copying the image per document is forbidden
Position it relative to the issuer block, slightly overlapping the address; same physical size across all three templates

"Just paste one image," I thought. I then got stuck in three different layers: infrastructure, the library, and the coordinate systems.

Problem 1: there was no private storage

My first idea was the existing S3 bucket that stores attachments and logos. Then I read its bucket policy:

{
  "Effect": "Allow",
  "Principal": "*",
  "Action": "s3:GetObject",
  "Resource": "arn:aws:s3:::<bucket>/*"
}

Principal: * with s3:GetObject — anyone who knows the key can read the object. No matter how careful the application code is, putting the seal there breaks the "never distribute" requirement at the storage layer.

The seal is a PNG of a few dozen KB, so I stored it in a PostgreSQL bytea column instead. If you never build a GET endpoint for the image, a public URL cannot exist by construction. The only consumer is the document renderer.

The seemingly contradictory pair "no copies, yet finalized documents are immutable" was solved by an append-only design:

Replacing the seal inserts a new row and repoints the company's "current seal" reference
Deleting the seal keeps the row and only cuts the reference
Finalizing a document snapshots the seal's row ID onto the document

Finalized documents keep pointing at the old row, so later changes never touch them. There is always exactly one copy of each image.

As a bonus finding, finalized PDFs were also sitting in that same public bucket under guessable keys. That was out of scope for this feature, so I filed it as an infrastructure task (prefix-level deny in the bucket policy) and handed it over.

Problem 2: POI's `resize()` trusts the font

Next, placing the image. With Apache POI I anchored the picture at the right edge of column F in the issuer block, set the anchor's dx, and called Picture.resize(scale). The seal ended up in the middle of the cell.

The cause is inside resize(): it re-derives the horizontal offset by estimating cell widths from font metrics. The template uses MS PGothic, and the estimate came out at roughly 60% of the real column width — so my carefully computed dx was overwritten based on a wrong premise.

The fix was to drop resize() entirely and compute all four corners of the twoCellAnchor (from/to col, row, dx, dy, in EMUs) myself:

XSSFClientAnchor anchor = new XSSFClientAnchor(
    fromDx, fromDy, toDx, toDy,
    fromCol, fromRow, toCol, toRow);
anchor.setAnchorType(ClientAnchor.AnchorType.MOVE_DONT_RESIZE);
Picture pic = drawing.createPicture(anchor, pictureIdx);

Row heights read back accurately from the template, so vertically I just accumulate rows until the required height is reached. I also set the shape's xfrm off/ext to the same values. Convenience methods hide their assumptions — here, the font.

Problem 3: there were three coordinate systems

The PDF output was still off in position and size. It turned out three separate layers transform coordinates, each modified at a different stage:

1. Cell width in "characters". Before PDF conversion, our pipeline enlarges fonts by 6pt and shrinks cell widths (which Excel stores in character units) proportionally to preserve the layout — e.g. 45.66 chars → 29.5 chars. Computing pixels from the shrunken value gives you a too-narrow cell. I multiply the font ratio back in first.

2. Print scale. The templates print at 61%, so 66 px on the sheet is 10 mm on paper. A kaku-in is conventionally 18–21 mm, which back-calculates to a ~110 px square on the sheet.

3. Millimeters on paper. The only layer anyone actually cares about. Luckily all three templates use the same 61% scale, so equal sheet pixels automatically satisfied the "same size everywhere" requirement.

Characters on the sheet, pixels on the sheet, millimeters on paper: ignore any one of the three and it looks right on screen and wrong on paper.

Verification: what ships on paper must be checked on paper

Unit-test templates are empty sheets, so they can't tell you what the paper will look like. I rendered 12 documents (3 real templates × long/short address × ON/OFF) with a dummy seal PNG, converted them with local LibreOffice, and cropped the top of each PDF to a PNG for eyeballing:

libreoffice --headless --convert-to pdf out/*.xlsx
pdftoppm -png -r 100 -y 0 -H 350 out/invoice.pdf check/invoice

All three "not yet" verdicts (not overlapping the address yet, too big, etc.) came from those images. The harness was deleted, not committed; what stayed in the repo were six unit tests: ON puts an anchor at column F with dx > 0, OFF renders no picture, ON with no registered seal renders no picture, text positions are identical between ON and OFF, and a finalized document keeps its seal after the company removes it.

Three small ones

H2 (PostgreSQL compatibility mode) in tests doesn't understand blob: a byte[] column with a 4 MB limit made Hibernate choose blob and the schema failed; lowering the limit to 1 MB switched it to varbinary
"The file won't select" → a WebP file against accept="image/png,image/jpeg"
The browser file input's default "no file selected" text looked out of place, so the input is hidden behind register/replace/delete buttons

Takeaways

"Private" breaks at the infrastructure, not in your code. Read the bucket policy before choosing a storage location. If the storage is public, your access control isn't
Convenience methods hide assumptions. POI's resize() estimates cell widths from fonts. When placement is off, go back to the low-level API (twoCellAnchor + EMU) and your own math
What ships on paper must be verified on (something close to) paper. Of the three coordinate layers, users only ever see the last one — verify in that layer

A "just paste one image" feature ended up spanning bucket policies to EMUs. Next time someone says "you just place it," I'll start by counting the coordinate systems.

The Unclickable Hamburger Button: Three Wrong Fixes Before I Found the CSS Bundle Order Bug

sunah kim — Fri, 16 Oct 2026 11:54:23 +0000

The report

QA filed this against our internal business web app (React + Vite):

The three-line icon next to the date can't be clicked

One screenshot attached. No device, no screen width, no description of what actually happened on click. From that single line, I fixed the wrong thing three times in a row — and the real culprit turned out to be the order of rules inside the production CSS bundle. Here's the whole detour, as it happened.

Context: there are two hamburger buttons

The sidebar behaves differently depending on viewport width:

Desktop (>900px): the sidebar is always visible. A "≡" button in the sidebar header collapses it into a 60px icon rail (the state is persisted in localStorage)
Narrow (≤900px): the sidebar becomes a drawer, and a "≡" appears in the app bar (next to the date) to open it

So there are two "≡" buttons, and the app-bar one is hidden on desktop via CSS:

.sidebar-toggle-mobile { display: none; }

@media (max-width: 900px) {
  .sidebar-toggle-mobile { display: inline-flex; }
}

The "three-line icon next to the date" in the report is the app-bar button. I immediately assumed the reporter was on a phone. That assumption was mistake number one.

Wrong fix #1: the collapsed state in localStorage

At 375px locally, everything worked. But when I set "collapsed=true" in localStorage, I could reproduce a state where the drawer opened only as a 60px rail — which does look like "nothing happens."

Convinced I'd found it, I shipped a fix that ignores the collapsed flag at narrow widths. The reporter's reply: "Same as before."

Wrong fix #2: the collapse button inside the drawer

Next I noticed the drawer still contained the desktop collapse "≡", which either shrank the drawer to a rail or did nothing. I replaced it with an "×" (close) button and hid the app-bar "≡" while the drawer was open. Second deploy.

The reporter answered:

I don't understand why there's a ≡ here at all

That one sentence was the decisive clue: they were seeing a "≡" outside drawer mode. And then came the detail that cracked it open:

I'm looking at this on a 16-inch MacBook

Desktop width. The button that display: none was supposed to hide was visible on a wide screen.

The real cause: rule order in the bundle

I downloaded the deployed production CSS bundle and located the two rules by byte offset:

.sidebar-toggle-mobile{display:none}   → at byte 8,975
.icon-btn{display:inline-flex}         → at byte 72,008

.icon-btn is a shared icon-button class, and this "≡" has it too. Both selectors are a single class, so their specificity is identical — and on a tie, the later rule wins. display: inline-flex was overriding display: none.

Why only in production? The sidebar.css imported by the component ended up earlier in the bundle than the entry point's index.css. An order that was harmless on the dev server flipped in the production build.

Suddenly every observation lined up. On desktop, the "≡" is visible. Clicking it does update state — but the drawer and the backdrop are both disabled by CSS at desktop width, so nothing on screen changes. "It can't be clicked" was a perfectly accurate observation.

The fix: a selector that doesn't depend on bundle order

The fix is one line — add a parent class to raise specificity:

.app-bar .sidebar-toggle-mobile { display: none; }

@media (max-width: 900px) {
  .app-bar .sidebar-toggle-mobile { display: inline-flex; }
}

Two classes beat one, wherever the rule lands in the bundle.

Verification was done against production-like builds: I served a local production build and confirmed the computed display was none at 1400px and flex at 375px. After deploying, I downloaded the actually-served CSS bundle again and grepped it to confirm the new rule was in.

Takeaways

Dev builds and production bundles can order CSS differently. When something is "only broken in production," look at the deployed bundle itself
Don't fill in the reporter's assumptions yourself. "It's a hamburger icon, so it must be a phone" is where the detour started. Ask for device, viewport width, and what exactly appeared on click — first
"Correct" fixes are the most dangerous ones. Each of my three fixes was a legitimate improvement in isolation. None of them fixed the reported problem

The decisive clue came from conversation, not code. The three questions to ask before attempting to reproduce: which device, which viewport width, and what exactly did you see when you clicked? Next time, I'm asking those first.

Connecting Zenn to a GitHub Repository: The Setup Steps and Two Pitfalls

sunah kim — Fri, 09 Oct 2026 11:54:46 +0000

Introduction

In my previous article, I introduced a pipeline that cross-posts from a single GitHub repository to Zenn, dev.to, and velog. I briefly touched on Zenn's GitHub integration there, but that part was actually where I stumbled first. In this post, I'll zoom in on just the integration: the correct setup steps, and the two pitfalls I actually ran into. If you follow the steps in this order, you should be able to avoid the same swamps.

(For context: Zenn is one of the most popular tech blogging platforms in Japan, and its killer feature is publishing articles by simply pushing Markdown to a connected GitHub repository.)

What the GitHub integration gives you

Once connected, pushing Markdown files under articles/ in your repository publishes or updates articles automatically. No web editor needed, and your articles get proper Git history. Private repositories work too, so your drafts and idea notes stay private while only the published articles become public.

The correct setup flow

Log in to Zenn and open "Deploy from GitHub" in the dashboard (zenn.dev/dashboard/deploys)
Start the connection from the "Connect repository" button on Zenn's side, then pick the target repository on GitHub's authorization screen (I recommend granting access to only the selected repository, not all repositories)
After the connection completes, pushing an article triggers a deploy, and the deploy log shows up in the dashboard

It looks completely unremarkable — the point is that you must start from Zenn's side.

Pitfall 1: Installing the app from GitHub's side doesn't connect anything

This was my first mistake. I installed the Zenn Connect app from the GitHub Marketplace first, and the connection never showed up in Zenn's dashboard. No error message either, so I had no idea what was wrong.

The cause is how the connection flow is designed. Zenn's GitHub integration assumes the OAuth authorization and repository selection happen from Zenn's own screen. Installing the app from GitHub's side alone never creates the link to your Zenn account. The official docs even state explicitly: if the app is already installed and you see this screen, uninstall it once and reconnect.

The fix: uninstall Zenn Connect from GitHub's Settings → Applications, then redo the connection from Zenn's "Connect repository" button. After that, it showed up in the dashboard immediately.

Pitfall 2: Commits pushed before connecting never get deployed

Just when I thought I was done, the next trap. Articles I had pushed before connecting never got deployed, no matter how long I waited.

The cause: only pushes made after the connection is established are detected as deploy targets. Existing commits are not processed retroactively.

The fix: push a new commit after connecting. An empty commit is enough.

git commit --allow-empty -m "trigger zenn deploy"
git push

That triggered the first deploy, and my existing articles finally appeared in the dashboard.

How article files work

Deploy targets live at articles/<slug>.md. The slug must be 12–50 characters of lowercase letters, digits, and hyphens — anything outside that range fails at deploy time. It's easy to pick a slug that's too short, so watch out.

The front matter looks like this:

---
title: "Article title"
emoji: "🔗"
type: "tech" # tech or idea
topics: ["zenn", "github"] # lowercase, up to 5
published: true # false means draft
---

Pushing with published: false keeps the article as a draft, so it's safest to verify your deploy setup with a draft first.

Summary

Always start the connection from Zenn's "Connect repository" button. If you installed the app from GitHub's side first, uninstall it and reconnect
Commits pushed before connecting are never deployed. Push an empty commit after connecting to trigger the first deploy
Slugs are 12–50 characters of lowercase letters, digits, and hyphens. Use published: false for drafts
Private repositories work, so only the articles go public while your writing history stays private

By the way, the pushes to this repository are themselves automated as a scheduled task run by an AI agent. The full picture is in my previous article if you're curious.

Building a Multilingual Blog Pipeline That Auto-Posts to Zenn, dev.to, and velog

sunah kim — Thu, 08 Oct 2026 11:54:30 +0000

Why I built this

As a Korean engineer working in Japan, I've long wanted to publish technical articles in three languages: Japanese on Zenn, English on dev.to, and Korean on velog. Manually copy-pasting every article into three platforms was never going to happen, so I built a pipeline with a single GitHub repository as the hub — push once, and the article goes out to all three platforms automatically.

I expected Zenn to be the easy part and got tripped up anyway, and velog turned out to have no official API at all. Here are the pitfalls I actually hit and how I solved them.

Overall architecture

The repo layout is simple — one directory per platform:

.
├── articles/   # Zenn (auto-deployed via GitHub integration)
├── devto/      # dev.to (GitHub Actions + official API)
├── velog/      # velog (GitHub Actions + GraphQL)
└── material.md # topic backlog

When I push an article, three things happen:

Zenn: the official GitHub integration detects changes under articles/ and deploys them
dev.to: a GitHub Actions workflow posts files under devto/ through the official REST API
velog: a workflow posts files under velog/ through velog's internal GraphQL API

Pitfall 1: Zenn's GitHub integration must be started from the Zenn side

My first stumble was Zenn itself. If you install the Zenn Connect app from the GitHub Marketplace side first, the integration never shows up in Zenn's dashboard (zenn.dev/dashboard/deploys).

The cause is the direction of the flow. Zenn's integration is designed so that the OAuth authorization and repository selection happen from Zenn's settings screen. Installing only the GitHub App from the GitHub side never creates the link to your Zenn account. Zenn's docs even say explicitly: if the app is already installed and you see this screen, uninstall it first and reconnect.

The fix was simple: uninstall the app on the GitHub side, then redo the integration from the "Connect repository" (リポジトリを連携する) button in Zenn's settings.

One more gotcha: commits pushed before the integration are never deployed. Only pushes after the connection is established get picked up, so if you have existing articles, you need a fresh commit after connecting. An empty commit works fine:

git commit --allow-empty -m "trigger zenn deploy"
git push

That kicked off the first deploy and my articles appeared in the dashboard. A nice bonus: private repositories work too, so your drafts and commit history stay private while only published articles go public.

Pitfall 2: dev.to wants the front matter inside the body

dev.to was the pleasant one, since there's an official API. The key point is that instead of sending title and tags as separate fields, you send the entire Markdown including front matter as body_markdown:

curl -X POST "https://dev.to/api/articles" \
  -H "api-key: ${DEVTO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"article": {"body_markdown": "---\ntitle: ...\npublished: true\ntags: ...\ncanonical_url: https://zenn.dev/...\n---\n\nBody here"}}'

The important field is canonical_url. Publishing the same content on multiple sites risks being treated as duplicate content by search engines, but pointing canonical_url at the Zenn original declares "this is the canonical source." Also, published: false lets you post as a draft, so it's safest to test the pipeline with drafts first.

Pitfall 3: velog has no official API

velog was the hard one. There is no official API, so I ended up calling the internal GraphQL endpoint used by the web frontend (v3.velog.io/graphql), authenticated with the login session cookies (access_token / refresh_token).

Then I hit a baffling behavior: if you pass null to the meta field of the writePost mutation, you get no error — just a null result. With no error message, I burned a lot of time figuring this out. The answer: pass an empty object {} instead.

mutation {
  writePost(input: {
    title: "...",
    body: "...",
    tags: ["..."],
    is_temp: false,
    meta: {}        # null fails silently
  }) { id url_slug }
}

Token handling has its quirks too. The access_token is short-lived, but if you send the expired one together with the refresh_token, fresh tokens come back via Set-Cookie. The workflow is supposed to pick those up and update the secrets — but the refresh token itself expires after roughly 30 days, so you have to manually re-grab the cookies about once a month. That's the operational weak point. For testing, is_temp: true saves the post as a draft, which is what I used during verification.

Operational details

One small but important detail: the Actions workflow only processes newly added files. Otherwise, every typo-fix push would re-post the same article:

git diff --name-only --diff-filter=A HEAD^ HEAD -- 'devto/*.md'

All API keys and cookies live in GitHub Actions Repository Secrets, injected as environment variables in the workflow. Never commit them in plaintext — and be careful not to echo them into logs either.

Summary

Start Zenn's GitHub integration from the Zenn side ("Connect repository" button). Pre-integration commits never deploy, so push an empty commit after connecting
For dev.to, put the front matter inside body_markdown and use canonical_url to avoid duplicate-content issues
velog requires the unofficial GraphQL API; pass {} (not null) as meta. Token expiry is the operational weak point
Process only newly added files (--diff-filter=A) to prevent double-posting

One last thing: the writing and translation side of this pipeline is handled by a scheduled AI agent (Claude) task. Every night it reads the topic backlog (material.md), writes an article, generates all three language versions, and pushes them. I'll cover that part in detail in a future post.

DEV Community: sunah kim

Twig 3.30 Broke Every Page of EC-CUBE with a 500 — Blame the Return Types Added in 3.12

Introduction

What happened — 500s everywhere and a Fatal error

The cause — return types on abstract methods in Twig 3.12.0

The fix — add return types to 5 overrides (6 lines)

Verification and rollback plan

Takeaways

The 3 Principles of Harness Engineering — Map, Enforce, Accumulate

Introduction

Mapping the 3 principles to Claude Code features

① The map — CLAUDE.md as a signpost under 200 lines

② Enforcement — don't mix "please" with invariants

③ Accumulation — Skills grow one per failure

Workflow in practice: build the harness before the app

Summary

References

Setting Up a Harness for Claude Code: Enforce Invariants with Hooks, Not Prompts

Tired of writing the same warnings every time

The cause: every rule was a "please"

The fix: a 48-line map + 4 hooks + 5 skills

Keep CLAUDE.md down to a 48-line "map"

Enforce invariants with PreToolUse hooks and exit 2

Vary how skills are invoked by blast radius

What went wrong, and what's still unverified

Takeaways

Open Any Finder Folder in VS Code with One Keystroke (Automator Quick Action)

Dragging folders gets old fast

Creating the Quick Action in Automator

1. Create a new Quick Action

2. Configure how input is received

3. Add "Run Shell Script"

4. Save

Assigning a keyboard shortcut

The key point: use open -a, not the code command

Summary

Reference

The Clipped Dropdown in a Collapsed Sidebar — the Hidden Meaning of overflow-y: auto

The QA report

Where I got stuck

The cause: one non-visible axis drags the other along

The fix: position: fixed only while collapsed

Takeaways

Permissions Hadn't Changed, but QA Said 'I Can't Create' — Answering with a Table Uncovered an Unreachable Branch

The question

Background: we had just changed how roles are stored

Trying to answer with a table, I read the code

The fix: drop TEAM_MEMBER from the early return

Answering QA

Takeaways

Stamping a Company Seal on Excel Invoices: No Private Storage, a Lying resize(), and Three Coordinate Systems

The task

Problem 1: there was no private storage

Problem 2: POI's resize() trusts the font

Problem 3: there were three coordinate systems

Verification: what ships on paper must be checked on paper

Three small ones

Takeaways

The Unclickable Hamburger Button: Three Wrong Fixes Before I Found the CSS Bundle Order Bug

The report

Context: there are two hamburger buttons

Wrong fix #1: the collapsed state in localStorage

Wrong fix #2: the collapse button inside the drawer

The real cause: rule order in the bundle

The fix: a selector that doesn't depend on bundle order

Takeaways

Connecting Zenn to a GitHub Repository: The Setup Steps and Two Pitfalls

Introduction

What the GitHub integration gives you

The correct setup flow

Pitfall 1: Installing the app from GitHub's side doesn't connect anything

Pitfall 2: Commits pushed before connecting never get deployed

How article files work

Summary

Building a Multilingual Blog Pipeline That Auto-Posts to Zenn, dev.to, and velog

Why I built this

Overall architecture

Pitfall 1: Zenn's GitHub integration must be started from the Zenn side

Pitfall 2: dev.to wants the front matter inside the body

Pitfall 3: velog has no official API

The key point: use `open -a`, not the `code` command

The fix: `position: fixed` only while collapsed

Problem 2: POI's `resize()` trusts the font