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) |
| 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 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, 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 |
| 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 |
| 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 |
| shell-scripting | BSD/GNU sed differences, zsh expansion quirks, 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, 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 |
Japanese versions live in docs/ja/ (Japanese is the authoring source).