ENGINEERING NOTES

技術_

AIエージェント開発、システム設計、ローカルLLMなど、技術者向けの知見を発信します。

技術
#AIエージェント#ai-operations#quality-gate#code-review

AI エージェントのパイプラインでレビュアーはどこに配置すべきか：全8話ですり抜けた欠陥から学ぶ「判断点」へのシフトレフト

AI エージェントによる多段制作パイプラインでは、独立レビュアーを成果物完成（生成点）ではなく骨格設計（判断点）に配置すべきです。コスト削減を狙って通し読みレビューを初回限定にした結果、後続全8話ですり抜けた実測ログに基づき、レビュアーを増やさず判断点へシフトレフトする設計原則を解説します。

Read Article →
技術
#AIエージェント#claude-code#ai-operations#prompt-engineering

プロンプトの肯定形書き換えで生じるルールの適用範囲ドリフトと差分点検の手順

プロンプトルールを否定形から肯定形へ書き換えると、意図せず適用条件や拘束力の範囲が広がる・狭まる・すり替わるといったドリフトが生じます。連載ルールセットの保守で発生した10件の変質実測をもとに、BeforeとAfterを3軸で突き合わせてズレを防ぐ差分点検手順を解説します。

Read Article →
技術
#claude-code#ai-cost-optimization#AIエージェント#llm#troubleshooting

Haiku を指定したのに費用の72%が Opus だった ── 子の claude -p に波及する advisor 設定と modelUsage 監査

claude -p で安価な小型モデル（Haiku 5.5）を指定しても、親セッションの /advisor 設定が波及して上位モデル（Opus 5.5）が透過的に呼び出され、費用の7割超を占める逆転現象が起きることがあります。実測ログに基づき、指定外モデルの課金混入の解剖、無効化による対照実験、modelUsage の自動監査と実行環境の分離策を解説します。

Read Article →
技術
#claude-code#AIエージェント#ai-cost-optimization#llm

「安いモデルは雑」は作業の型で逆転する ── Claude Code サブエージェント3モデルの実測比較

Claude Code のサブエージェント委任におけるモデル順位は、タスクが局所的な事実抽出か広域の網羅探索かという作業の型によって逆転します。Haiku 5.5・Sonnet 5.5・Opus 5.5 の同一タスク実測に基づき、死んだ URL や引用改変の発生差、所要時間・費用を比較した選定基準を解説します。

Read Article →
技術
#github-actions#ci-cd#actions-cache#ubuntu#troubleshooting

GitHub Actions を macOS から Ubuntu に移して費用を 1/10 にするときに踏んだ 3 つの罠 ── Taskwarrior 3 の MSRV 1.91.1 と ${{ env.ImageOS }} の空振り

GitHub Actions の Private リポジトリで macOS ランナーの 10 倍課金とキュー枯渇を解消するため ubuntu-latest へ移行する際、最新ツールの apt 不在、Cargo.toml の MSRV 1.91.1 乖離、actions/cache の key 式で ${{ env.ImageOS }} が空振りするスコープ仕様という 3 つの実務トラップを一次実測ログから解説します。

Read Article →
技術
#quality-gate#testing#ai-operations#code-review#ci-cd

実コード抜粋の行単位照合で踏んだ3つの境界：二重エスケープ事故の検出とAI検収ハーネス

ドキュメント内のコード抜粋を行単位で一次資料と機械照合する検査器の実装では、JSON文字列値のみのデコード、一次資料側限定のdiff接頭辞除去、および記号行の最大塊連結照合という3つの境界条件が重要になります。公開記事での二重エスケープ検出や閉じ括弧連続の偽陽性解消の実例とともに、人間が直接コードを見ないAIレビュー・検収ハーネスの運用思想を解説します。

Read Article →
技術
#markdown#quality-gate#testing#ai-operations#python

Markdown の行内コードスパン崩れを検出する 73 行の Linter を書いたら、スタック近似が CommonMark §6.1 の交差規則と衝突した

Markdown のインラインコード（コードスパン）でバッククォートが入れ子になり偶数のまま途中で割れる事故を CI で検出するため、CommonMark §6.1 の前方走査に合わせつつスパン内側で奇数回現れる同長列だけを交差例外とする 73 行の Python Linter を設計・改修した記録を解説します。

Read Article →
技術
#testing#quality-gate#simulation#mutation-testing#rust

過去のバグ4件を防ぐために書いた長期テストを、コード変異（Mutation）で逆検証したら半分しか捕まらなかった

50年（1,250期）回す長期回帰テストを追加して Green になったものの、コードレビューで過去のバグ4件を埋め戻す変異（Mutation）で逆検証したところ、別経路（移住）によるマスクやアサーション不在により想定通りに捕まったのは半分（2件）でした。回帰テストを過信せず「バグを再注入して赤になるか」を確かめる手順と、実測に合わせてコメントを誠実にリファクタリングする判断軸を解説します。

Read Article →
技術
#testing#parallel-execution#git#macos#troubleshooting

テスト並列化で 405 秒→175 秒にしたのに単独 43 秒のテストが 730 秒かかった理由 ── macOS の opendirectoryd / XProtect 競合と Git maintenance 抑止

macOS で短命サブプロセスを多用するテストを並列化すると逆に遅くなる原因は、OS 共有デーモン競合と Git local transport 時の自動保守実行にあります。直列 405 秒から 175 秒への短縮後に単独 43.9 秒のテストが並列 730.9 秒へ劣化した実例をもとに、GIT_TEMPLATE_DIR による設定注入やシバン直指定、flock 排他で 217.95 秒へ復旧させた実践設計を解説します。

Read Article →
技術
#rust#AIエージェント#コードレビュー#品質管理

型を広げた理由のコメントは、検算するまで正しいか分からない ── i128 が i64 で足りていた話

整数オーバーフロー修正で AI が付与した「和と積が i64 を超え得る」という理由コメントは、定数から最悪値を手計算すると i64 に対し約10万倍の余裕がある完全な誤りでした。もっともらしい解説を鵜呑みにせず、入力上限と定数の積を手元で検算して不要な 128bit 化を防ぐレビューの判断軸を実務の一次ログから解説します。

Read Article →
技術
#テスト設計#rust#wasm#品質管理#ミューテーションテスト

位置で対応させた手書き JSON のテストは、入力値が重なっていると取り違えを見逃す

手書き JSON の単体テストで出力全体をパースして比較していてもフィールドの取り違えを見逃すのは、テスト入力データ内で値が重なっているとスワップ変異が偶発的に等価になってしまうためです。本記事では言語境界の実測ログをもとに、入力値の対称性が生む偽陰性の死角と、全値相異テストデータおよび自己検証（メタアサーション）による堅牢化手法を解説します。

Read Article →
技術
#AIエージェント#情報検索#自然言語処理#taskwarrior#アーキテクチャ

タスク重複検出が32件中31件に当たった ── 閾値を上げると本命が消えるのでIDF順位づけに変えた

タスクの重複検出で誤検知を閾値で足切りすると本命まで脱落するため、二値判定を諦めて共有トークンの逆文書頻度（IDF）による順位づけへと転換した実務設計と教訓を解説します。

Read Article →
技術
#ai#claude-code#tmux#オーケストレーション#automation

画面に「esc to interrupt」があれば応答中、は本文に負ける ── 判定語が完了報告に載って3600秒待った

対話型AIエージェントの端末画面をスクレイピングして状態監視する設計の落とし穴を解説。完了報告本文の自己言及による3600秒STOPや非同期待機の誤読を防ぐ探索スライス設計と、通知フックへの移行指針を提示します。

Read Article →
技術
#shell-script#bash#troubleshooting#automation#ai-operations

取得に失敗しても「0件」と表示され、「無い」と読まれる ── 2週間で4か所直した「未確認」と「0件」の区別

外部コマンドの取得失敗を空リストへフォールバックさせると、「データが 0 件（正常）」と「取得失敗による未確認（異常）」が混同され、サイレントフェイルを招きます。Bash のプロセス置換や Python での実務トラブル 4 例をもとに、即座の停止（Fail Fast）と未確認への 3 値化設計を解説します。

Read Article →
技術
#cdp#wasm#nodejs#ブラウザ自動化

Chrome 拡張で長い試行を回すと、CDP が45秒で切れる ── 同じ Wasm を Node から呼んで推移表を最後まで取った

Chrome 拡張や CDP 経由のブラウザ自動化で長時間のシミュレーションを実行すると、45秒（45,000ms）で Runtime.evaluate がタイムアウトし、待機しても戻り値は回収できません。本記事では、同一の Rust/Wasm ソースから wasm-bindgen の --target nodejs で Node.js 実行環境へ計算を切り離し、推移表を完走させてブラウザ画面の描画値と突き合わせた検証アーキテクチャを解説します。

Read Article →
技術
#claude-code#ai-operations#quality-gate#typescript#testing

記事に載せた CI ログに、実際の tsc は出さない「Found 30 errors」が書いてあった ── もっともらしいツール出力を実機の形と照らす

TypeScript の tsc は CI 環境などの非TTY実行時に、集計行を出力せずエラー各行をファイル座標付きで表示します。自社連載制作でAIがエラー定義ひな形から捏造した架空のCIログの発覚と実機検証の実例をもとに、ドキュメントに載せるツール出力を推測で作文させず実機で決定論的に取得・検収する品質管理と運用の設計思想を解説します。

Read Article →
技術
#image-generation#mermaid#ai-operations#quality-gate#troubleshooting

画像化で作り直しになる図は、要素数で事前に分かれた ── Mermaid の札12・矢印10を上限にした根拠と手集計が2セル違っていた話

画像生成 AI で図解を作る際のリトライや 429 エラーは、Mermaid の要素数（札12・矢印10・戻り0・最大流入2）を手前で抑えることで事前に防げます。自社連載16図の実績から上限ルールを導出し、手集計での2セル誤りを経て自動検査スクリプトを実装した運用の教訓を解説します。

Read Article →
技術
#testing#quality-gate#simulation#AIエージェント

テストもレビューも通ったシミュレーションを50年回したら、男児が9人から1人に減った ── 1期の不変条件のテストは期をまたぐ振る舞いに届かない

1期の不変条件（保存則）を満たすテストだけでは、微小な端数切り捨てや処理順序の偏りが期をまたいで累積するドリフトを検出できません。自作ゲームのシミュレーションにおいて、単体テストとCIを通過したコードが50年間の実行で人口凍結や男女比崩壊を起こした実例から、SafetyとLivenessの違い、および時間を早送りして長期推移を検収する決定論的シミュレーションテスト（DST）の設計を解説します。

Read Article →
技術
#Mac#security#tls#verification#troubleshooting

「更新した」のに mise の Python と Homebrew の Git は漏洩 CA を信頼していた ── Mac の信頼ストア多重構造と実測検証

Mac でツールを更新しても、Homebrew の Git や mise の Python は未修正の /etc/ssl/cert.pem を参照し続ける盲点があります。eMudhra の CA 鍵漏洩対応の実測から、ツールごとの信頼ストアの違いと、遮断（陽性）と正規疎通（陰性対照）をセットで点検する検証手順を解説します。

Read Article →
技術
#swift#spm#macos#shell-script#troubleshooting

テストは通るのにアプリが起動直後に落ちた理由 ── SPM リソースバンドル欠落と存在確認 if のサイレント障害

SPM でビルドした macOS アプリが Bundle.module の未検出でクラッシュする主因は、パッケージングスクリプト内の存在確認 if が未検出を素通りさせたことにあります。単体テスト通過とアプリ組み上がりの環境差異、および未検出時に即座に落とすフェイルファスト設計を解説します。

Read Article →
技術
#ブログ#automation#ssg#refactoring#technical-debt

図の Mermaid ソースを本文のコメントに残す運用を、147記事分まとめて捨てた ── Git にあるものを本文に二重に持たない

静的サイトで図を画像化した後、元ソースを HTML コメントに残す運用はエスケープ事故と過剰な検査スクリプトを招きます。画像化前のコミット履歴を信頼し、147記事・243ブロックの二重管理を一括削除した実務の経緯と判断軸を解説します。

Read Article →
技術
#image-generation#prompt-engineering#ai-operations#troubleshooting

画像生成AIの図解で「パ」が「バ」に化ける ── 部分編集で直さず、崩れない語に言い換える

画像生成AIの図解作成で濁点・半濁点の文字崩れを防ぐには、事後の部分編集で直そうとせず、構成段階で崩れにくい語に言い換える方が早く通りました。編集を重ねて利用枠の上限（429）に達した失敗と、パ行・バ行を含む語を言い換えて2枚・全17ラベルを一発で一致させた実務記録から、制作パイプラインの判断軸を共有します。

Read Article →
技術
#claude-code#AIエージェント#llm#ai-cost-optimization#コードレビュー

別系統のモデルに第二意見を任せる ── 完走したモデルと返らなかったモデル、そしてサブエージェントはトークンの9%だった

Claude Code のサブエージェントや検証処理を Gemini や Kimi などの別系統モデルに委譲する際、多ファイル横断での完走可否や maxTokens 設定、数値丸めのリスクを実測検証。セッション全体のトークン内訳を測るとサブエージェントは全体の9%（メイン会話が91%）に過ぎず、分散の効果を見極める前にまず内訳を測るべき理由を解説します。

Read Article →
技術
#AIエージェント#ai-operations#prompt-engineering#process-design#システム設計

構造案にセリフを書くと、3割が公開本文にそのまま残る ── AI 連載で構想段階に決めるものを絞った

AI エージェントに連載を段階生成させる自社パイプラインでは、構造案に書いたセリフの約3割が公開本文へ逐語で残っていました。36話の実測を起点に、構想では「制約と技術」だけを先に決め、セリフは執筆直前に決める境界設計を解説します。

Read Article →
技術
#code-review#llm#AIエージェント#subagents

AIレビュー3巡24件の指摘で、2つの軸が同じ欠陥を指していたのは3組だった ── 私が退けた1件の記録つき

私のセッションが実在と判定した24件の指摘のうち、2つの軸が同じ欠陥を指していたのは3組（6件）で、どれも同じ巡に並べた2軸レビュー（14件）の間でした。別モデル（agy／Gemini）の単発レビュー2巡と、規約と仕様に観点を分けた2軸レビュー1巡を、AI エージェントの役割定義を変えた1つの変更に当てた結果です。1巡目の指摘を私のセッションが範囲外として空振りに数え、3巡目に同じ文書の欠落が挙がって直した1件も記録します。

Read Article →
技術
#AIエージェント#llm-as-a-judge#ai-operations#quality-gate#url-verification

正しい指摘が「別の文献に同じ事実がある」という理由で誤検出に降格されていた ── 所在の検査と事実の検査は別物

多段LLMパイプラインにおいて、検証役（Verifier）の指摘を「別の文献に同じ事実がある」ことを理由に誤検出として降格すると、文献の所在を問う正当な指摘が握りつぶされてしまいます。自社システムで起きたRFC 9110の脚注誤りインシデントをもとに、世の中の真偽を問う「事実性の検査（Factuality）」と指定文献の記述を問う「所在の検査（Citation Attribution）」の根本的な違いと、誤検出フィルタの再設計ルールを解説します。

Read Article →
技術
#AIエージェント#ai-operations#subagents#quality-gate

委譲したエージェントが started=no を返したのに、実は作業を終えていた ── 完了の偽陰性と、報告前に実物を見る手順

AIエージェントへの作業委譲でタスク完了や未着手を正確に判定するには、中継ツールの終了コードやステータスフラグ（中間観測値）を鵜呑みにせず、報告前にGit logやタスク状態などの客観的成果物（実物）を直接検証することが不可欠です。本記事では、委譲先がstarted=noを返しながら裏でタスクを完了させていた実インシデントをもとに、完了の偽陰性のメカニズム、判定の3値化、および他者の報告を事実と説明に分ける現場規律を解説します。

Read Article →
技術
#testing#refactoring#git#perl#code-review

消えた検証を戻したら、既存テストが逆向きに落ちた ── 弱い挙動を前提に書き換わったテストの洗い方

リファクタリングで脱落した検証を戻した際、不正値を受け入れる弱い挙動を前提にしていた既存テストが逆向きに落ちる現象が発生します。型制約による例外メッセージ変化の罠、grep による前提テスト洗い出し、push 済みブランチのレビュー空振りを防ぐ main...HEAD 差分検証まで、実務ログに基づき解説します。

Read Article →
技術
#AIエージェント#claude-code#context-engineering#ai-operations#品質管理

規則を足すと、Claude が普段やっていることが消える ── 8規則と2規則で実測したプロンプトの規則の選び方

プロンプトや CLAUDE.md に規則を足しすぎると、モデルが自発的に行っていた完了条件の提示などの良い振る舞いが押しのけられます。架空題材3種・計75本の実測ログをもとに、指定しなくても守られる no-op 規則を削り、最小限の規則だけを選ぶ手順を解説します。

Read Article →
技術
#ドキュメント#リンクチェック#quality-gate#ci-cd#automation

目次リンク42本が、全部「同じ日の別の回」を指していた ── 対象一覧を手作業で作ると、漏れは一覧の外に出る

ブログの連載目次リンク42本が同日の別記事を指し、通常のリンクチェッカーを素通りした障害事例。手作業やheadによる作業一覧作成の罠を解剖し、設定の正本（SSoT）からの機械的導出と、結果の空間に対するタイトル一致検査による決定論的な検証手法を解説します。

Read Article →
技術
#AIエージェント#quality-gate#testing#process-design

AIで書いた連載を読み直したら、第3回のコードが第2回の検証を黙って落としていた ── 回をまたぐ後退は各回のレビューでは捕まらない

各回のレビューを通過して完結した技術連載を読み直したところ、前の回で実装した入力検証やテストが後続回の完成コードで密かに削ぎ落とされていた実態が発覚しました。局所レビューをすり抜けるサイレント後退の構造的盲点と、前回のテストスイートを次回の完成コードに機械実行する決定論的ゲートによる品質担保の仕組みを解説します。

Read Article →
技術
#perl#claude-code#token-efficiency#legacy-modernization#ai-cost-optimization

AI コーディングで Perl はどれだけ割を食うか ── 13言語ベンチを Perl だけ追試した

公開ベンチマーク ai-coding-lang-bench における Perl の AI コーディング効率とは、新規作成（v1）では試行錯誤で時間を要する一方、既存コードへの機能拡張（v2）では JavaScript に迫る全体4位の速さを示すという非対称な特性です。Claude Code による追試ログと失敗原因の内訳から、既存 Perl 資産の保守・拡張における判断軸を解説します。

Read Article →
技術
#ai-operations#logging#process-design#human-in-the-loop

AI が作る一次記録には「書き手の操作」が入らない ── 公開当日に証言で書き直した記事から、記録に無い操作を訊くタイミング

AI エージェントが作る作業記録には、書き手の手作業が構造的に入りません。初版公開から再公開まで 54 分の手戻りが発生した実例をもとに、記録に無い操作をセッション直後の一次ログ採取段で書き手に訊く工程設計を解説します。

Read Article →
技術
#AIエージェント#ai-operations#quality-gate#loop-engineering

強く書けば反証され、正確に書けば自明になる──看板主張が収束しなかった企画の記録

AIエージェントのレビューループが収束しない原因は、下流の修正ミスではなく企画段階の「不可能性・限界を看板にした主張」にあります。成果物13ファイル・1,427行を生成しながら本文0文字で破棄された実測ログを基に、強く書けば反証され正確に書けば自明になるジレンマの構造と、企画段階で早期遮断するFail Fastゲート設計を解説します。

Read Article →
技術
#quality-gate#ci-cd#linter#testing

出典ゼロの記録は、実在性監査ゲートの検査対象からすり抜ける ── 「空虚な真」を防ぐ品質ゲートの分母設計

出典URLの実在性を検査する監査ゲートが、出典を1本も持たない記録を「違反0件」として合格させていた。論理学の「空虚な真（Vacuous Truth）」が引き起こすサイレントパスの構造と、pytestやJestの設計思想、等級から分母を捉えるフェイルセーフな品質ゲートの作り方を解説します。

Read Article →
技術
#AIエージェント#web-scraping#ai-operations#quality-gate#encoding

「取得成功」判定が文字化けを見逃す ── URL取得ゲートの死角と決定論的フォールバック

HTTP 200 かつ十分な文字数（wordCount）があっても、文字化けしたテキストは検知ゲートを素通りします。@IT記事（CP932）取得での失敗インシデントをもとに、文字数チェックの限界と、iconv と素のタグ除去へ垂直に降りる決定論的フォールバック設計を解説します。

Read Article →
技術
#AIエージェント#claude-code#デザインシステム#フロントエンド

デジタル庁デザインシステム（DADS）を Claude Code の設計図にする ── DESIGN.md をゼロから書かずに AI スライドのデザインを統一する

Claude Code などの AI で作るスライドや UI のデザインを統一するには、DESIGN.md をゼロから書くより、デジタル庁デザインシステム（DADS）が公式配布する Markdown から余白・文字・色の値を借りて要約するのが近道です。145 ファイルを丸ごと渡さずエッセンスに絞る理由と、ルールでは防げない描画崩れを実物で検収する手順も整理します。

Read Article →
技術
#prompt-engineering#llm#テクニカルライティング#制限言語

「ASD-STE100 の規則に寄せて」は日本語でも効くか ── 8規則で完了条件が9本中4本に減り、2規則なら残った

日本語プロンプトで航空宇宙の制限言語 ASD-STE100 の規則に寄せて書かせると誤読は防げるのか。8規則を指定すると完了条件が半減した実測データと、完了条件が残った「2規則」への絞り込みを解説します。

Read Article →
技術
#llm-architecture#ai-cost-optimization#subagents#claude-code#llm-evals

検証系サブエージェントは安価モデルに任せられるか ── コスト構造と委任境界の設計指針

明確な合否基準を持つ検証系サブエージェントは、小型・安価モデルへ委任できるというのが筆者の仮説です。トークンの入出力単価差、キャッシュ損益分岐点の試算と、決定論的テストとの多層防御設計から、モデル選定の境界線を解説します。

Read Article →
技術
#shell-script#mise#運用自動化#エラーハンドリング

command -v を通るのに起動できない ── mise の shim が「抽出失敗」の誤報を生んだ

command -v が成功するのにコマンドが実行できない原因は、command -v が POSIX 仕様上コマンドを呼び出さず、shim 等の存在だけで終了ステータス 0 を返すためです。自社運用の実例をもとに、形式的な存在確認から実態を伴う起動確認（ヘルスチェック）への転換と作法差の落とし穴を解説します。

Read Article →
技術
#testing#shell-script#bash#quality-assurance#troubleshooting

基準値の算出に失敗しても検査は成功し続ける ── BSD 専用 date -v が空文字になり、鮮度チェックの射程がゼロになった

動的に算出する基準値が空文字になると、Bash の文字列比較では全件が条件を満たして検査の射程がゼロになります。BSD 専用の date -v が GNU coreutils の date で実行されて空文字になり、キャッシュ鮮度判定が永久に素通りした実インシデントをもとに、辞書順比較の仕様や結果行の心理的死角を解剖。「原因の予防」だけでなく「結果の検収」を置く防御策を論じます。

Read Article →
技術
#AIエージェント#mcp#アーキテクチャ#オープンソース#llm

次世代AIエージェント基盤「Pi 1.0」を解剖する：CodemodeとPi Durableが示すハーネスの設計思想

オープンソースのAIエージェント基盤「Pi 1.0」と実験的拡張「Pi Durable」は、Codemodeによる動的サンドボックス実行とSQLiteによるステート永続化により、トークン肥大化とクラッシュ耐性を同時に解決します。その設計思想と実務活用の勘所を解剖します。

Read Article →
技術
#claude-code#AIエージェント#security#権限設計

AI エージェントに .env の値は隠せるか — Claude Code の deny が塞ぐ経路、塞がない経路

Claude Code で .env の読み取りを deny しても、値がエージェントに届く経路は残る。Claude Code に実際に試させた結果と公式ドキュメントから、deny・サンドボックス・モデルの判断がそれぞれどの経路を塞ぐかを整理し、最後に残る「人間」という経路まで扱う。

Read Article →
技術
#launchd#troubleshooting#monitoring#Mac

launchd の自動 deploy が起動前に失敗し、ログには何も残らなかった ── 死活は成果物の更新日時で見るのが向いている

launchd のジョブが起動前に失敗すると、ジョブ自身のログには新しい行が増えません。plist の旧パスで spawn failed（exit 78）になった実例と、launchctl print の見方、gh-pages の更新日時で死活を見る理由と限界をまとめます。

Read Article →
技術
#AIエージェント#shell-script#parallel-execution#environment-variables#ai-operations

環境変数で渡したはずの設定が、受け側の無条件代入で上書きされていた ── 4並列の分離が効いていなかった話

並列ジョブを環境変数で分離したつもりが、受け側の無条件代入で上書きされ、4並列がすべて同じ台帳へ書いていた。実行は成功し続けた。再現実走の数値と、代入行の点検手順をまとめます。

Read Article →
技術
#ai-operations#troubleshooting#automation#yaml

「タイトルにキー名を書かない」と記録した後も、同じ YAML エラーは16日後と25日後に起きた──記録は失敗の前にセッションへ現れなかった

YAML のタイトルにコロンと空白を入れると壊れます。避け方を学び記録に残した後も同じエラーが16日後と25日後に再発し、2回とも失敗の前に記録はセッションに現れませんでした。3回の逐語と、テンプレートの title をクォートする1行の修理を示します。

Read Article →
技術
#claude-code#AIエージェント#code-review#whiteboard#quality-gate

「クリックしたのに違う場所に飛ぶ」の正体──Whiteboard のリンクは全部正しく、ずれていたのはラベルだった

AI に描かせた図からコードへ飛ぶ Whiteboard で「違う場所に飛ぶ」と感じた原因を、22 の行範囲（延べ 30 参照）の照合と確認用の図で切り分けました。誤った参照はゼロで、ずれていたのはリンクのラベルでした。

Read Article →
技術
#claude-code#claude#llm#ai-operations

Claude Opus 5.5 で Claude Code はどう変わる？ — 何もしなければ effort は medium で動く

Claude Code v2.1.280 で Opus 5.5 が Pro と Team Standard の既定モデルになり、effort の既定は Opus 5 の high から medium に変わりました。ユーザー設定に残した旧形式の effortLevel も効きません。手元の Claude Code の記録で実際に起きたことと、effort の確認・選び直しの手順を整理します。

Read Article →
技術
#ローカルLLM#llm#apple-silicon#claude-code

macOS 27 の「fm」コマンド入門 — API キーなしで使えるが、M1 Pro ではコーディングエージェントのモデルにならなかった

macOS 27 に標準で入った fm コマンドを、使えるようになるまでの待ち方から fm respond・fm schema・fm serve まで実測で解説。M1 Pro では 4,096 トークンの AFM 3 Core が載り、opencode をつなぐと上限超過で止まった。

Read Article →
技術
#AIエージェント#claude-code#context-engineering#品質管理#ai-operations

レビュー役に「まず読め」と書いた1行が、答えを渡していた ── 同じ漏洩が経路を変えて3回起きた

レビュー用サブエージェントに「まず◯◯を読め」と書いた1行が、検証中の仮説をそのまま渡していました。断定 → 禁止の理由文 → 必読ファイルと経路を変えて3回届いた漏洩の記録と、ファイルを読ませる運用ごとやめた設計判断です。

Read Article →
技術
#AIエージェント#loop-engineering#quality-gate#ai-operations

差し戻しループを止めたのは周回数ではなかった ── 検証記録68件で数えた2つの停止装置

エージェントの差し戻しループを止めるには回数上限で十分か。自社ログ68件の実測から、周回数カウンタ（0/43）より先に欠陥クラスの再発検知（4/38）が決着させていた事実と、その実装パターンを解説します。

Read Article →
技術
#AIエージェント#ai-operations#quality-assurance#llm-guardrails#troubleshooting

AIは『やっていない検証』を具体的なバージョン番号付きで語る——品質ゲートのトリガー漏れが起きた実例

AIエージェントが実施していない検証を実在するバージョン番号付きで捏造し、品質ルールの条件漏れですり抜けた実例を解剖。決定論的ゲートとフォールバック設計の原則を解説します。

Read Article →
技術
#AIエージェント#ai-operations#human-in-the-loop#生産性向上#claude-code

AIエージェントに任せた仕事の「監視コスト」を実測する：上流予防（88万）と下流手戻り（1,885万）の20倍の格差

AIエージェントにタスクを委任した後の「監視コスト（Botsitting）」を解剖。自社パイプラインのトークン実測値（88万 vs 1,885万）に基づき、タスク委任の3つの境界基準と非同期ガバナンス設計を解説します。

Read Article →
技術
#legacy-code#testing#refactoring#perl#characterization-test

レガシーコードの特性テストで直面する「グローバル状態とDB汚染」の隔離 ── 状態リセットとインメモリDBへの安全なSeam切り

特性テスト導入直後に立ちはだかる「テスト順序依存」や「DB汚染」。動的スコープによる状態リセット、トランザクションロールバック、インメモリDBやTest::mysqldへのSeam切りという3つの実践パターンで安全に副作用を隔離する手順を解説する。

Read Article →
技術
#quality-gate#ai-operations#testing#docs-as-code

5層のCI/レビューをすり抜けた設計文書の積層破損 ── 検査対象の「被覆表」がないと起きる死角

5層の品質検査をすり抜けて上流設計文書が破損・マージされた実事故から、検査対象の末端偏重という構造的死角を解明。全成果物を網羅する「検査被覆表（Coverage Matrix）」と決定論的リント設計を解説します。

Read Article →
技術
#AIエージェント#claude-code#agents-md#context-engineering#testing

「消すな」と書いたコメントごと消える ── AIエージェントの自己参照的削除と外部テストによる防護

AIエージェントにプロンプトやルールの刈り込みを任せると「消すな」と書いたHTMLコメントごと規約を削除する事故が起きます。自然言語防護の限界と、外部テストによる見出しアサーション設計を解説します。

Read Article →
技術
#AIエージェント#llm#process-design#品質管理#context-engineering

「いつ作ると何が変わるか」—— AIエージェントの一括生成で12話中11話が既出だった事故回避

AIエージェントにタスクやコンテンツを一括生成させると、なぜ重複事故が起きるのか。新シリーズ12話中11話が既出だった実体験から、一括生成前に自問すべき3つの確認規律と二段構えの既出照合スクリーニング設計を解説します。

Read Article →
技術
#adr#設計レビュー#アーキテクチャ#ai-operations#レビュー

ADRに「却下」と書いた設計がそのまま実装された──記録の矛盾を見落とす「読んだつもり」の落とし穴

「ADRを書いているから」「多重AIレビューを回しているから」という安心感の裏で、なぜ却下した設計が12話中11話で実装されてしまったのか。実例から学ぶ確証バイアスと、解釈を排して実物を数え直す設計レビュー規律。

Read Article →
技術
#AIエージェント#パイプラインデザイン#ROI分析#品質管理#プロセス改善

品質ゲートの配置は「検出率」ではなく「手戻りコスト × 発生頻度」で決める ── 実測1,884万トークンの教訓

AIエージェントの多段ワークフローで品質ゲートをどこに置くべきか。自社ブログパイプラインで実測した約1,884万トークン（18,840,956）の手戻りと、企画段階での予防コスト882,723トークンの比較から、「検出率」ではなく「手戻りコスト × 発生頻度」でゲートを配置する判断基準を解説します。

Read Article →
技術
#タスク管理#意思決定#task-management#ai-operations#運用設計

「次回確認する」で保留した課題は、次回が来ない ── 条件付き保留の構造的欠陥と日付満期の設計

「次回起きたら判断する」「様子を見る」という保留はなぜ放置されるのか。実務ログの棚卸し実例から、条件付き保留の構造的欠陥と、日付満期（TTL）による自律的なタスク運用ルールを解説します。

Read Article →
技術
#AIエージェント#ai-operations#業務自動化#システム設計#生産性向上

「記事」ではなく「型」を資産にする ── AI と組んで技術連載200本を生み出したフレームワークと分業設計

ゼロからの執筆に息切れしていませんか？技術発信の真の資産は個別の記事本数ではなく、再現可能な「型（メタ構造）」です。完結9シリーズ204本を生み出した「職業ドラマ翻訳」フォーマットと、品質を保証する人間と AI の分業パイプライン（Phase 0〜7）の設計論を解説します。

Read Article →
技術
#システム設計#css#変更容易性#デザイントークン#受託開発

前日の設計決定を撤回したら、diff は35行だった

「ブログはダーク維持」という設計決定を翌日に全面撤回した際、修正はわずか5ファイル・35行で完了しました。変更コストは決定の重さではなく値の集約度で決まるメカニズムと、CSS変数による2層トークン設計を実測データから解説します。

Read Article →
技術
#ストラングラーフィグ#データ移行#システム設計#legacy-modernization#アーキテクチャ

ストラングラーフィグの本当の難所は、切り替えではなく並行稼働中のデータ二重管理

ストラングラーフィグパターンによる段階的移行で最も手が止まりやすい「並行稼働中のデータ二重管理」を解説。Dual Writeの破綻要因、会員・注文・在庫ごとの正マスタ配置、JITパスワード移行による切り戻し不能点（PNR）の設計まで、実務で壊れないデータ移行の手順を整理します。

Read Article →
技術
#受託開発#AI導入ガバナンス#経営とAI#開発プロセス#claude-code

受託でAIを使うとき、顧客への説明と合意に何を書くか

受託開発でAIを活用する際、顧客への説明と合意に何を書くべきかを解説。モデル選定・データ経路・非学習・保持期間・再委託の5項目を整理し、確認チェックリストと合意書ひな形を提供します。

Read Article →
技術
#legacy-code#testing#characterization-test#perl#refactoring

テストが1本もないレガシーで、最初の1本をどこに書くか

テストが1本もないレガシーコードに対して、最初のテストは「仕様を追う」のではなく「現状を固定する」characterization test（特性テスト）から始める。選定基準、書き方、カバレッジの読み方まで、Perl / Mojolicious を例に実務的な手順を解説する。

Read Article →
技術
#docker#legacy-modernization#perl#technical-debt#troubleshooting

10年前の依存は公式 Dockerfile では復元できない ── レガシーの Docker 化で最初に折れる場所

10年以上動いている Perl や PHP、Ruby のレガシーアプリを Docker 化しようとして、初日の依存解決で挫折する理由（推移的依存の最新化・消えた配布物・ビルド依存）と、スナップショット固定による現実的な脱出手順を解説します。

Read Article →
技術
#AIエージェント#claude-code#ai-cost-optimization#プログラミング言語選択#token-efficiency

コード生成のトークン効率は言語選択でどう変わるか ── TypeScript/Python/Bashで同一タスクを書かせて実測する

AIエージェントに同一タスクをTypeScript/Python/Bashで書かせ、トークン消費量を実測。最大2.1倍の差の正体と、言語選択より効くコスト最適化の視点を解説します。

Read Article →
技術
#claude-code#AIエージェント#llm-as-a-judge#code-review#ai-operations

サブエージェントの「高」判定を、そのまま信じない ── 一次情報で再評価して進行可を出した事例

AIによる自動検証が「重要度: 高」と出した指摘を、そのまま採用せず「出典は実在するか」「記事の核心を支えるか」の2観点で再評価し、格下げして進行を許可した1件の実例を、一次記録に基づいて追体験します。

Read Article →
技術
#ローカルLLM#Mac#AI開発#moe#apple-silicon

ローカルLLM Expert Streaming時のSSDランダムI/Oボトルネック実測 ── 速度ブレの裏でディスクリートリードは何が起きているか

常駐1.5GBで26B MoEモデルが動く裏で発生する「同一入力での推論速度2.8倍のブレ」。前作で未計測だったI/O側ボトルネックをMacのiostat実測データで解剖。decode中平均900MB/s〜1.5GB/sの連続リードとCPU idle 77〜81%が語る物理的実態を解明します。

Read Article →
技術
#AIエージェント#claude-code#agent-harness#cost-optimization#ai-operations

スキルの進捗表とHarnessのリマインダーが二重管理を生む：ツール呼び出し29回 vs 0回の実測ケーススタディ

AIエージェントの実行基盤（Harness）が出すタスク更新リマインダーに素直に従うと、ツール呼び出しが急増しAPIコストが悪化する二重管理の罠を、5セッションの実測比較データと現場ルールを交えて解説します。

Read Article →
技術
#AIエージェント#ai-operations#quality-gate#constraint-tax

指摘に全部対応したら、何も言っていない記事になった — 抑制的な制約が積み上がるとき

AIエージェントの品質ゲートの指摘に愚直に対応した結果、抑制的な制約が26項目まで膨らみ、約9,300字の完成原稿が主張のない無難な文章になってボツになった一次実録です。Over-Constraining (Constraint Tax) の構造と失敗の学びを解説します。

Read Article →
技術
#AIエージェント#soft-404#url-verification#shell-script#ai-operations

AIエージェントのWeb調査検収で起きた2つの罠 — HTTP 200を返すSoft 404と正規表現汚染

AIエージェントが出力した出典URLをcURLで自動検証した際、HTTP 200を返すSoft 404や正規表現パースバグによって無効なURLがすり抜けた29件中7件の実測ログと、ロバストな検収スクリプト設計の手法を解説します。

Read Article →
技術
#llm#AIエージェント#api-design#prompt-engineering

「話題の記事」の判定をLLMに任せると壊れる──APIで取得・ソートし、解釈だけを任せる設計パターン

Web検索エージェントに「高スコアな記事」を収集させると、順位判定だけが崩壊する現象が発生します。Hacker News API の実測データ（最高405pt vs 最低1pt）と論文をもとに、決定論的処理とLLM解釈の正しい役割分担を解説します。

Read Article →
技術
#quality-gate#code-review#ai-operations#log-analysis

記事の根拠になっている一次計測ログを、どの工程も検証していなかった──品質ゲートが見落としていた「生データ検証」の盲点

AIレビューやCI/CDなどの「品質ゲート」を導入して文章表現の整合性をチェックしていても、根拠となる一次計測ログの集計・解釈誤りは検出できません。276KBの生ログ再集計で主張が真逆になった実例から、検証パイプラインの盲点を解説します。

Read Article →
技術
#AIエージェント#citation-verification#ai-operations#hallucination

AIエージェントに調査を委譲したら、出典の半分が検証不能だった

AIエージェントによる調査委譲で「出典付き回答」を過信していませんか？スタンフォード大の研究データ（Citation Recall 51.5%）や実用上の劣化パターンから、自動検算ゲート（Citation Verification Gate）をパイプラインに組み込む設計手法を解説します。

Read Article →
技術
#AIエージェント#llm#architecture#automation

LLM に逐語転記をさせない — 委譲の損益分岐を「生成」と「転記」で切る

AIエージェントへの業務委譲でプロンプト調整の沼にはまっていませんか？タスクの規模ではなく「生成（確率的）」か「転記（決定論的）」かで切り分ける明確な委譲基準と、100%の再現性を実現するスクリプト連携手法を解説します。

Read Article →
技術
#ローカルLLM#ベンチマーク#Mac#AI開発

ローカルLLMのベンチマークは何回測るべきか ── 16回連続測定で分かった「1回測定」の罠と分散表記のすすめ

同一の Mac とプロンプト条件で 16 回測定したところ、推論速度が 4.3〜11.9 tok/s（2.77倍）も動揺しました。スワップや熱などの探求プロセスを開示し、1回測定の危険性と「複数回試行＋分散表記」の標準テンプレートを提案します。

Read Article →
技術
#AIエージェント#prompt-engineering#ui-ux#human-in-the-loop#システム設計

AIエージェントに複数選択を迫らせると会話コストが増える理由 — 選択肢ラベルの二重化事故

AIエージェントや支援ツールとの対話で、複数確認時に選択肢番号が重複する「ラベル二重化事故」と画面がブロックされるモーダルUIの課題を解説。一問一答原則と「直交ラベル命名規則」により1打鍵で即答できるプロンプトUI設計を提案します。

Read Article →
技術
#AIエージェント#ハルシネーション対策#human-in-the-loop#データ検証

文章をレビューさせるな、ログを再集計させろ──AIレビューの使いどころを1段変える

「AIにレビューさせています」は、LLMを意見を下す「Judge」として使っているに過ぎません。文章の根拠になった生データや引用元に立ち返って確認する「検算」でしか見つからない誤りがあることを、自分の分析が実際に覆された記録から示します。

Read Article →
技術
#ローカルLLM#Mac#AI開発#moe#apple-silicon

26Bモデルが常駐1.5GBで動いた──ただし同じ入力で16回測ったら速度が2.8倍ブレた

メモリに載らないMoEモデルをSSDストリーミングで動かすTurboFieldfareを、前回Ollamaで挫折したのと同じM1 Pro 16GBで実測。常駐1.5GB・スワップ増加ゼロという約束は守られましたが、同じ入力での16回の計測が4.3〜11.9 tok/sとブレました。原因を追ってpowermetricsまで回した記録です。

Read Article →
技術
#tokenmaxxing#ai-cost-optimization#agents-md#llm-architecture#claude-code

「Tokenmaxxing」狂騒曲の終焉：大容量コンテキスト依存から脱却する実用的AIコスト最適化設計

1M+の大容量コンテキスト全投入（Tokenmaxxing）によるコスト急増や精度悪化の技術的リスクを解き明かし、Cascading AGENTS.mdやモデルルーティングによりコストを90%以上削減する実用的AIアーキテクチャ設計を解説します。

Read Article →
技術
#AI導入ガバナンス#claude#プライバシー設計#ベンダーリスク管理#情報セキュリティ

「意図通りの動作です」で済ませていいのか──Claude共有チャット流出事故に見るAI導入ガバナンスの盲点

医療記録や暗号資産の秘密鍵まで検索結果に露出したClaude共有チャット流出事故。「noindex設定忘れ」という単純化を超え、robots.txtとnoindexの技術的な自己矛盾、公開URLの本質的な統制不能性から、AIツール導入時にベンダーの説明を鵜呑みにしないためのガバナンス視点を解説します。

Read Article →
技術
#オープンウェイトAI#AI導入ガバナンス#ベンダーロックイン#経営とAI#マルチモデル戦略

Nvidia・Microsoft・Metaが「オープンウェイト規制」に反対する理由から読み解く、AIベンダー選定のリスク管理

2026年7月、Nvidia・Microsoft・Metaなど80団体規模が「オープンウェイトAIへの拙速な規制に反対する」公開書簡を発表しました。同時期のMythos・GPT-5.6の配布制限、Kimi K3とDeepSeekのライセンス差、報道でばらつくトークンシェアの数字を手がかりに、AIモデル選定を「性能」だけでなく「主権・ガバナンス」の軸で見直す視点を解説します。

Read Article →
技術
#経営とAI#エンジニアリング組織#ソフトウェア品質#AI導入ガバナンス#claude-code

コーディングは「解決」したのに、なぜソフトウェアは劣化し続けるのか──ボトルネックは「書く」から「決める」に移っただけだった

Hacker Newsで876人が支持した「なぜソフトウェアは劣化し続けるのか」という問いから、GitLabとFaros AIの独立した調査データを手がかりに、AI時代の「書く速度」と「決める速度」の非対称という経営課題を読み解きます。

Read Article →
技術
#AI#agentic-workflow#ai-operations#retrospective#process-design

AIパイプライン運用における「振り返り」の設計論──事故をルールに沈殿させ、過剰規制を防ぐメタプロセス

LLMエージェントによる自動化パイプラインにおいて、障害やハルシネーションを単発のプロンプト修復で終わらせず、システム仕様へ還元する「振り返り」の設計論。In-Loop/Out-of-Loopの二層構造、ルール沈殿、過剰規制（Constraint Tax）の防止策を解説します。

Read Article →
技術
#claude-opus-5#AIエージェント#llm#失敗談#コンテキスト肥大化

Opus 5 にブログを書かせてみたが、ボツにした理由──上位モデルでも超えられなかった「合格ライン」の壁

Claude Opus 5 でブログ自律執筆を試みるも生成記事をボツにした実態記録。5時間枠の70%がわずか30分で消失したコスト構造と、スクショ追加による自律メタ解析誘発、敵対的レビュー（blog-verify）4周の無限ループの原因を解き明かします。

Read Article →
技術
#ollama#ローカルLLM#claude-code#Mac#AI開発

Claude Codeの制限対策にOllamaを試して痛感した、ローカルLLMのリアルとクラウドAIのありがたみ

Claude Code利用量上限の逃げ道としてOllamaでローカルLLM導入を試みたリアルな体験談。M1 Pro Macでのスワップや遅延の現実、最新クラウドAPI（Claude Haiku 4.5, Gemini 3.6 Flash）とのコスト比較を通じ、クラウドとローカルの正しい使い分けを解説します。

Read Article →
技術
#AIエージェント#context-engineering#harness-engineering#agents-md#システム設計

Loopを回す前に『ハーネス』を整えよ：AGENTS.mdの階層分割とmiseで実現する堅牢なAI開発基盤

単発のVibe Codingや自律Loopの前に必要な『ハーネスエンジニアリング』を解説。巨大なAGENTS.mdによるLost in the Middle現象を防ぐ階層分割モデルと、miseによる決定論的な検証環境（Self-Verification）の構築手法を提示します。

Read Article →
技術
#AI時代キャリア#system-fluency#アーキテクチャ#AIエージェント#コードレビュー

AIスキルだけではキャリアを守れない──今エンジニアに求められる「システム説明力（System Fluency）」とは

CursorやClaude Code等のAIツール普及により、プロンプティング技能はコモディティ化しました。建設業界の「丸投げ構造」とのアナロジーから、AI時代に生き残るコアスキル「System Fluency（システム説明力）」と、AIを評価パートナーに変える実践アプローチを解説します。

Read Article →
技術
#AIエージェント#loop-engineering#context-engineering#システム設計#claude-code

プロンプトを磨くのはもうやめよう。「Context」を整え「小さなLoop」を回すAIエンジニアリング実践

単発のプロンプト入力（Vibe Coding）に頼る開発は限界を迎えています。事前に適切な構造化文脈を与えるContext Engineeringと、機械的テストで自動検証するLoop Engineeringの導入手法を、20行のBashスクリプト等の具体例付きで解説します。

Read Article →
技術
#gemini#AIエージェント#アップデート#システム設計#llm

GoogleがGemini 3.6 Flash / 3.5 Flash-Lite / 3.5 Flash Cyberを発表！AIエージェント開発はどう変わるか

Googleが発表したGemini 3.6 Flash、3.5 Flash-Lite、3.5 Flash Cyberの全貌を解説。トークン消費最大65%削減、350tpsの超高速処理、セキュリティ特化モデルの登場がAIエージェント開発に与える影響とモデル選定の指針を整理します。

Read Article →
技術
#claude-code#claude#生産性向上

Claude Codeの週次利用制限と付き合う配分術──「/usage」で可視化し、ヘビーなタスクを計画的に投入する

Claude Codeの週次利用制限に週の後半で毎回突き当たる悩みを、`/usage`コマンドによる可視化と、タスクの重さに応じた配分計画で解消する方法を解説。あわせて2026年5月13日〜8月19日に実施された週次利用制限50%増量キャンペーンの内容も記録します。

Read Article →
技術
#claude#claude-code#AIエージェント#アップデート

Claudeが料金体系を大幅アップデート！Pro/Teamユーザーに配られた「$100移行クレジット」の正体と正しい確認・活用方法

2026年7月20日のClaudeの仕様変更に伴い、Pro/Team Standardユーザーに配布された$100クレジットについて徹底解説。Claude Codeで消費するための環境変数の注意点や、Fable 5のフォールバック・セーフガードの挙動など、エンジニア向けに技術仕様を分かりやすくまとめました。

Read Article →
技術
#claude-code#AIエージェント#開発環境#生産性向上

Claude Codeを「リアルなエンジニアの道具」にする：mattpocock/skillsを導入して気づいた、AI協働開発の新しい仕事術

Claude Codeで再利用可能なワークフローを定義する「mattpocock/skills」の導入体験レポート。自動化の限界であるコンテキスト肥大化を防ぐ「人間主体のAI制御」という設計思想の魅力に迫ります。

Read Article →
技術
#AIエージェント#業務自動化#システム設計#claude-code

「一つのことをうまくやる」スキルを、壊さずに束ねる。ブログ執筆パイプラインにオーケストレーターを追加した話

5つに増えたAIエージェントスキルを毎回手動で順番に呼び出す運用に限界を感じ、既存スキルの中身を一切変更せずに束ねるオーケストレーター機能を追加しました。UNIXの哲学「一つのことをうまくやる」を、工程の設計だけでなく工程同士の繋ぎ方にまで適用した記録です。

Read Article →
技術
#AIエージェント#業務自動化#システム設計#claude-code

AIに『必ず間違いがある』前提でレビューさせる。ブログ執筆パイプラインに懐疑的検証ゲートを足した話

執筆の前工程（企画・設計）で記事の品質の大部分は決まる、という体感から、設計書を懐疑的な視点で見直す/blog-verifyステージと、それを迂回できなくするハードゲートを追加しました。人間の『見直し』とAIの自己レビューの違いを起点にした設計思想です。

Read Article →
技術
#AI#ブログ#効率化#実践ガイド

AIを活用した効率的なブログ執筆術

Meetsourceの技術ブログを実際に支えている、AIエージェントとの分業のコツを紹介します。一発生成に頼らず、企画・執筆・校閲を分けて任せることで得られた実務的な知見です。

Read Article →