nlink-jp のエンジニアリングナレッジベース — 組織のプロジェクト横断で得られた知見を テーマ別ドキュメントに集約したもの。各項目は事象 → なぜ → 適用方法の構造を持ち、 出所を一般化した形で記載している。
English version: README.md
- 作る前に読む — 本書がカバーする領域の設計・実装に着手する前に、該当ドキュメントを 読む。
- 学んだら還元する — 作業中に再利用可能な知見が生まれたら、その作業の完了の一部として ここへ還元する。
いずれも組織ポリシー — CONVENTIONS.md （§Consult and feed the knowledge base）と ADR-015 を参照。
ドキュメントは main を読んで利用する（リリースは無い）。
| ドキュメント | 内容 |
|---|---|
| release-engineering | 署名・notarization・Homebrew tap・リリースアーカイブ・版数・ライセンス表記 |
| macos-gui | SwiftUI/AppKit の罠、メニューバーアプリ、macOS 27の実現性・間隔検証、リンクした SDK が外観を決める、Wails |
| web-ui | WebView フロントエンドと自己完結 HTML レポートの CSS/レイアウトの罠 |
| mcp-server-design | MCP プロトコルの制約、OAuth discovery の限界、stdio 衛生、構造化エラー、LLM 向けツール設計、文書 id 付き offset ページング、ファイル出力先は呼び出しごとの引数 |
| llm-integration | Gemini/genai SDK、出力検証、drift、トークン、dedup、パイプライン、エージェントのツール除外、判定モデルは thinking でなく世代で選ぶ、ローカルサーバの接頭辞キャッシュと system プロンプト、再送上限は再生計測で、ローカルモデルが常置指示に行動する場所（system ではなく最初の user メッセージ） |
| security | プロンプトインジェクション対策、秘密情報/PII、公開サービス、破壊的操作の安全設計、ラップできないツール説明文の隔離、sandbox 内のツールチェインキャッシュ、有限領域があるならカーネルへ判定を移し無いなら規則を置かない、dialer 内で閉じる SSRF |
| build-and-packaging | CGO クロスビルド、.gitignore の罠、CI 不使用の判断理由 |
| testing | 実データ E2E、モック設計、失敗注入、MCP テストハーネス、クロスプラットフォーム検証、エラー文言の質、診断時の証拠の質、ログの時刻表現、独立検証パスの収束判定、新しい境界は本物を本物の檻で駆動して検証、モデル比較ベンチの設計、inline TUI の行計算は tmux で実測、複数行を占める出力は自分の下を消す、端末の能力プローブ、モデルが読む文面を機械照合、境目に接する区間の切断漏れ、ヘッドレスのテストとビュー描画カウンタ、同時1クライアントのフィクスチャと並列スイート、直さない欠陥の固定 |
| containers-and-infra | macOS の Podman、DuckDB bind mount、matplotlib フォント、ログローテート、SSH 死活監視、case-sensitive ボリュームの禁忌、Podman 上の QEMU/TCG による実ゲスト OS、VMのデバイスを製品の使い方に合わせる |
| config-and-io | Bubble Tea の Update 内 Send による凍結、canonical 識別子、strict 設定デコード、データ保持期限、保存先変更と reconcile、ボリューム空き容量、OAuth、ターミナル IO、任意の応答で開いたままになる送信窓 |
| shell-scripting | BSD/GNU sed 差、zsh 展開の癖、Bash trap スコープ、置換の罠、bash 3.2 の set -u と空配列 |
| embedded | M5Stack / ESP32 の知見 |
| development-process | rewrite/refactor 判断、コントリビューション triage、ADR 粒度、ドキュメント作法、アーカイブ済みリポの分離、submodule の破損、報告と制御、移植コードの ADR 引用、upstream への提案が望まれているかの見極め |
英語版は docs/en/（日本語が原文）。