The nlink-jp engineering knowledge base — lessons learned across the organization's projects, compiled into themed documents. Each entry follows a symptom → why → how to apply structure and cites its origin in generalized form.
日本語版は README.ja.md を参照。
- Consult before building — when starting design or implementation work in a domain covered here, read the relevant document first.
- Feed back what you learn — when work surfaces new reusable engineering knowledge, contribute it here as part of completing that work.
Both practices are organization policy — see CONVENTIONS.md (§Consult and feed the knowledge base) and ADR-015.
Documents are consumed by reading main — there are no releases.
| Document | Contents |
|---|---|
| release-engineering | Signing, notarization, Homebrew tap, release archives, versioning, licence notices |
| macos-gui | a menu bar panel's state is yours to keep (isShown lags a close), SwiftUI/AppKit traps, menu-bar apps, macOS 27 feasibility and spacing validation, the linked SDK deciding an app's appearance, dumping the layer tree when views look right, Wails, neither CFPreferences nor the plist telling at write time whether a preference was saved (measure a failure on the real target before designing for it), deriving a window's minimum size from SwiftUI content by measuring the laid-out result, binding .keyboardShortcut once per form a key arrives in, an identifier NLLanguageRecognizer does not know making that language undetectable, languageHints acting as a prior only when it lists every language, AVSpeechSynthesisVoice picking the region for a bare language code |
| web-ui | CSS/layout traps in WebView frontends and self-contained HTML reports |
| mcp-server-design | MCP protocol limits, OAuth discovery limits, stdio hygiene, structured errors, LLM-facing tool design, offset paging with a document id, per-call file output roots |
| llm-integration | Gemini/genai SDK, output validation, drift, tokens, dedup, pipelines, agent tool exclusion, choosing a judge model by generation not thinking level, a small judge does not tell risky tool calls apart, a local server's prefix cache vs the system prompt, retry bounds from replayed requests, where a local model acts on standing directives (first user message, not the system prompt) |
| security | Prompt-injection defense, terminal injection through a renderer that decodes character references, secrets/PII hygiene, internet-facing checklist, destructive-op safety, quarantining unwrappable tool descriptions, toolchain caches inside a sandbox, moving a judgment to the kernel where one exists and deleting the rule where none does, SSRF closed inside the dialer, a sandbox-writable directory reached through an os.Root opened from the vouched directory, a credential following a redirect only inside the domain the request started in, comparing places by identity rather than name on a case-insensitive disk — a place that does not exist yet included, names folded as the disk folds them, ffmpeg as an interpreter (pin every input's format, keep what it writes and reads back out of caller- and sandbox-writable places), distinguishing real error-shaped files using metadata and measured forced-download responses |
| build-and-packaging | CGO cross-builds, .gitignore traps, CI-less release rationale; preventing AppleDouble entries in Linux release archives built on macOS |
| testing | Real-data E2E, delivery verification, mockability, failure injection, MCP test harnesses, cross-platform verification, error-message quality, evidence quality when diagnosing, log timestamp semantics, convergence of independent verification passes, driving the real artifact through a new boundary, model-comparison bench design, measuring inline TUI rows in tmux, multi-row output erasing below itself, terminal capability probes, compiling the prose a model reads, interval cuts at a boundary a segment only touches, view-draw counters in headless tests, naming the layer a gate observes, single-client fixtures and parallel suites, pinning a defect you are not fixing, stalls on credit-controlled channels, completion signals when the writer preallocates, fakes that answer every question the same way, kitty's graphics protocol taking PNG only, keeping a dependency's slot until its cancel is answered (and measuring whether it is), looking for a marker only inside what it describes, recording a person's check per item and per method, testing drawing against a record of what is drawn (recorded inside the primitive), running the tests' properties at run time (one function, a strict flag, a generator that makes every form), inline images taller than the screen or on screen at a clear (lost differently per terminal), checking a port of a generated parser against the generator's own output, rerunning every earlier mutant after adding a check, porting iteration by how it walks (a port matching every output can still hang), comparing a ported part within the whole real pipeline (and taking the union of readings), checking what is drawn rather than the room kept for it, pinning rules that a rate floor cannot see, sorting a map-built list before picking its first item |
| containers-and-infra | Podman on macOS, DuckDB bind mounts, matplotlib fonts, log rotation, SSH liveness checks, why case-sensitive volumes break things, a real guest OS with QEMU/TCG under Podman, matching a VM's devices to the product, the ephemeral-port allocate-then-bind race, podman's unanchored name filter |
| graphics-and-fonts | Go's font.Drawer drawing tofu and dropping glyph failures (decide glyph presence per character, fall back per face, refuse what no face has), .ttc faces readable one by one, sfnt.Name not choosing a language |
| config-and-io | Bubble Tea's Send-from-Update freeze, Canonical identifiers, strict config decode, data retention expiry, storage-dir reconcile, volume free space, OAuth, terminal IO, send windows held open by an optional reply, a terminal query read from a goroutine leaves a reader that takes the next input, a time budget stated once, a checked number that becomes a zero Duration, a path in hand fed back through a text grammar, recording a guessed value apart from a fact and comparing only facts, directional rounding of exclusive timestamp bounds, storing "none" as a value for a key with a registered default, a terminal cell's aspect ratio read from TIOCGWINSZ rather than assumed or queried |
| shell-scripting | BSD/GNU sed differences, zsh expansion quirks (a glob given to git -C expands in the current directory), Bash trap scope, substitution pitfalls, empty arrays under set -u on bash 3.2, $? after an if statement, ! grep reading an error as no match, telling an unfetched input from an empty answer, git rev-parse without --verify, xargs on empty input |
| embedded | M5Stack / ESP32 lessons |
| development-process | Rewrite-vs-refactor, contribution triage, checking that contribution rules are written anywhere when outside PRs keep breaking them (organization-default CONTRIBUTING), vetting an outside PR by exporting it and only compiling, judging a feature proposal by the defined scope, asking a fork that ships binaries under upstream's name and checking its reply, sweeping the documents that refer to an archived tool, ADR granularity, docs practice, separating archived repositories, broken submodules, reports vs controls, ADR citations in ported code, judging whether an upstream proposal is wanted, replaying vendored patches against upstream, suspecting your own patch first, turning a recorded lesson into a check, remapping line citations by diff, convergence of an independent pass in rounds, resolving references instead of comparing pairs, an umbrella fetch writing into its submodules, measuring by section before parallelizing, no trace of use not being evidence of no demand when the feature is unusable, porting a parser generator's lexer rules in order, a regex tried at every token reading to the line's end making lexing quadratic |
Japanese versions live in docs/ja/ (Japanese is the authoring source).