8月4日は「橋の日」なのだそうです。
「8（は）4（し）」の語呂合わせで、川や橋に感謝しよう、という日だと聞きました。同じ語呂合わせで「箸の日」でもあるそうで、どちらの「はし」にしても、何かと何かをつなぐ道具の日です。
初投稿の日をわざわざ選んだわけではありません。カレンダーを見て気づいたとき、ちょっとうれしくなっただけです。でも、エンジニアというのは、こういう小さな偶然に意味を見つけたがる生き物なので、今日はこの「橋」を勝手に今回のテーマにさせてください。
はじめまして。生成AIとWeb開発を専門にしている、フリーランスのエンジニアです。今日から、Qiitaに記事を書いていきます。
この記事は初投稿のごあいさつですが、「よろしくお願いします」だけで終わらせるのはもったいないので、少し欲張ります。
- AIに聞けばたいていの答えが返ってくる今、なぜわざわざ人間が技術記事を書くのか
- これから記事を書くにあたって、自分に課すことにした7つの約束
- 逆に、書かないと決めたこと
- そして、これからどんな記事を書いていくのか
技術的な話は少なめです。外は連日の猛暑なので、冷たい麦茶でも片手に、のんびり読んでいただければうれしいです。
まずは、少しだけ自己紹介を
自己紹介というのは、どうしてこうも照れくさいのでしょうか。自分のプルリクエストの説明なら何行でも書けるのに、自分自身の説明となると、急に手が止まります。
なので、ここは割り切って、エンジニアらしく設定ファイル風にまとめてみます。
role: フリーランスエンジニア（生成AI × Web開発）
experience:
coding: 10年以上（学生時代のPHPとWordPressから）
professional: 8年
ai_development: 6年
main_stack:
backend: [PHP, Laravel, Python]
frontend: [Next.js, React, Vue.js]
cms_nocode: [WordPress, Shopify, STUDIO, Framer, Wix]
ai: [RAGチャットボット, LLMアプリ開発, Slack / LINE Bot]
infra: [AWS]
likes:
- 原因不明のバグの原因が分かった瞬間
- 誰にも気づかれない、地味な改善
- 猫（動画を見ているだけで、たいていの不具合は許せる）
……設定ファイルにした途端、人間味が一気に消えてしまいました。もう少しだけ、普通の文章で補足させてください。
プログラミングとの出会いは、学生時代に触ったPHPとWordPressでした。テーマのfunctions.phpを1行書き換えたら、サイトが真っ白になって何も表示されなくなる。WordPressを触ったことのある方なら、たぶん一度は見たことがある、あの真っ白な画面です。エラーメッセージすら出ない画面を前に途方に暮れたのが、私のエンジニア人生の、わりと正確なスタート地点だと思います。
それから10年以上たち、今は主にこんなお仕事をしています。
- 社内規程やマニュアルを読み込ませたRAGチャットボットの構築
- Laravel / Next.js を使ったWebアプリケーションの開発
- 不動産・医療・美容などの業種のWordPressサイト制作
- Slack / LINE Bot による業務の自動化
- 「AIを業務にどう使えばいいか分からない」という段階からのAI導入のご相談
AWSの認定資格（Solutions Architect – Professionalなど）や応用情報技術者試験など、資格もいくつか持っています。ただ、資格の数と障害対応の腕前は別物だということは、本番環境で何度も思い知らされてきました。資格は地図で、現場は天気です。地図をどれだけ覚えても、夕立の日に傘を持っていなければ、ずぶ濡れになります。この時期は特に。
なぜ、今さら技術記事を書くのか
「聞かなくても答えが返ってくる」時代
正直に言うと、Qiitaに書こうと決めるまで、かなり迷いました。
今は、人に聞かなくても答えが手に入る時代だからです。
エラーメッセージをAIに貼れば、数秒で原因の候補と修正案が返ってきます。エディタの中のAIアシスタントは、こちらが質問する前に、もうコードの続きを書き始めています。Stack Overflowで新しく投稿される質問の数がピーク時から大きく落ち込んでいる、という話も、もう珍しいニュースではなくなりました。
かつて私たちは、分からないことがあると検索して、誰かの書いた記事にたどり着き、そこで助けられてきました。私自身、Qiitaの記事に何度救われたか分かりません。深夜、誰かが何年も前に書いた「〇〇でハマった話」という記事の中に、自分とまったく同じエラーメッセージを見つけたときの、あの安堵感。あれは、ちょっとした奇跡でした。
その「誰かの記事に助けられる」という体験そのものが、AIに置き換わりつつあります。
だとしたら、これから人間が技術記事を書く意味は、どこにあるのでしょうか。
「ほぼ正しいけれど、ちょっと違う」
答えのヒントは、意外なところにありました。
Stack Overflowが毎年行っている開発者調査の2025年版（Stack Overflow Developer Survey 2025）です。AIツールを「使っている、または使う予定」と答えた開発者は84%。前年の76%からさらに増えて、もはや使っていない人のほうが少数派です。
ところが、同じ調査の中に、こんな数字が並んでいます。
- AIの出力の正確さを信頼している開発者は約33%。信頼していない開発者は約46%
- 「非常に信頼している」と答えた人は、わずか約3%
- AIを使っていて困ることの1位は、「ほぼ正しいけれど、ちょっと違う解決策」（"AI solutions that are almost right, but not quite"）で、**66%**が挙げている
- そして、AIの答えが信頼できないとき、**75.3%**の開発者が「人に聞く」と答えている
これを読んだとき、思わず「分かる……」と声に出してしまいました。
AIの答えは、たいてい「ほぼ正しい」のです。8割、9割は合っている。でも、残りの「ちょっと違う」の部分で、私たちは何時間も溶かします。しかも厄介なことに、「ほぼ正しい」答えは、まったく見当違いの答えよりも、間違いに気づくのが遅れます。
そして、その「ちょっと違う」を見抜くのに必要なのは、たいてい誰かが実際にハマった経験です。「そのライブラリ、このバージョンだと挙動が違うんですよ」「本番環境だとそこでタイムアウトします」「公式ドキュメントにはこう書いてあるけど、実際はこう動きます」。こういう話は、実際に手を動かして、痛い目を見た人の中にしかありません。
AIの答えが信頼できないとき、4人に3人が人に聞く。技術記事は、その「人」の役割を、時間と場所を越えて果たせる数少ない手段だと思っています。
AIがくれるのは「答え」、人が残せるのは「経緯」
もう少し言葉にすると、こういうことです。
AIは答えをくれます。でも、その答えにたどり着くまでの経緯は、まだ人間の側にしか残っていません。
「なぜその設計を選んだのか」「最初にどんな間違った仮説を立てたのか」「どこで3時間溶かしたのか」「結局、何が決め手だったのか」。こうした経緯は、答えそのものよりも、次に似た問題にぶつかったときに役に立ちます。
そして経緯は、たいていコードにもドキュメントにも残りません。書いた本人の頭の中にだけあって、放っておけば、そのうち本人も忘れます。三か月前の自分が書いたコードを読んで「誰だこれ書いたの」とつぶやいた経験は、きっと多くの方にあるはずです。犯人はいつも、三か月前の自分です。
ドナルド・クヌースは、1984年に発表した論文「Literate Programming（文芸的プログラミング）」の中で、こう書いています。
Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.
（プログラムの作り方についての伝統的な態度を改めよう。コンピュータに何をすべきかを指示することが主な仕事だと考えるのではなく、コンピュータに何をさせたいのかを人間に説明することに集中しよう）
40年以上前の言葉ですが、AIがコードを書いてくれる今のほうが、むしろ響く気がします。コンピュータへの指示は、AIがかなり肩代わりしてくれるようになりました。だからこそ、「何をさせたいのか」「なぜそうするのか」を人に説明する力の比重が、エンジニアの仕事の中で大きくなっているのだと思います。
技術記事は、答えと人とのあいだに架ける、小さな橋のようなものです。今日が「橋の日」だから言っているわけでは……少しあります。
結局のところ、自分のためでもある
かっこいいことを並べましたが、正直に言うと、半分は自分のためです。
「情けは人の為ならず」ということわざがあります。よく「情けをかけるとその人のためにならない」という意味だと誤解されますが、本来は「人に情けをかけておけば、巡り巡って自分に返ってくる」という意味です。
技術記事を書くことは、まさにこれだと思っています。人に説明しようとすると、分かったつもりになっていた部分が、驚くほどくっきり浮かび上がってきます。「あれ、ここ、なんでこう動くんだっけ？」と手が止まる。調べ直す。そこでようやく、本当に理解する。読んでくれた人の役に立つより先に、書いている自分がいちばん得をしているのです。
自分との7つの約束
さて、ここからが本題です。
書くと決めたからには、いい加減なものは出したくありません。かといって、完璧を目指して一本も出せないのでは本末転倒です。そこで、これから記事を書くうえで「これだけは守る」という約束を、7つ決めました。
公開しておけば、破ったときに誰かが指摘してくれるはずなので、あえてここに書いておきます。言ってみれば、自分で自分に書く仕様書です。
約束1：自分の手で動かしたコードだけを載せる
当たり前のようで、意外と難しい約束です。
記事を書いていると、「たぶんこう書けば動くはず」というコードを載せたくなる瞬間があります。でも、「たぶん動く」と「動いた」のあいだには、深くて暗い川が流れています。その川に落ちるのは、記事を読んでコードをコピーした読者のほうです。橋を架けるつもりが、落とし穴を掘っていた、では笑えません。
なので、記事に載せるコードは、必ず自分の環境で実行してから載せます。そして、どのバージョンで動かしたのかも、できるだけ書き添えます。半年後に読んだ人が「動かないんだけど？」となったとき、それがバージョンの違いなのか、記事の間違いなのかを切り分けられるようにするためです。
Linuxの生みの親、リーナス・トーバルズの有名な言葉があります。
Talk is cheap. Show me the code.
（口で言うのは簡単だ。コードを見せてくれ）
Linuxカーネルのメーリングリストでの発言として知られる言葉ですが、技術記事にもそのまま当てはまります。私なりに一言付け足すなら、「Show me the code that actually runs.」です。
約束2：数字には、必ず但し書きを付ける
「処理速度が10倍になりました」「精度が98%になりました」。技術記事には、こういう数字がよく出てきます。私も使います。数字は強いからです。
でも、数字は強いぶん、一人歩きもしやすい。「10倍」は、どのデータ量で、どんな環境で、何と比べて10倍なのか。「98%」は、どんなテストデータで測った98%なのか。そこが抜けた数字は、事実でありながら、読む人を誤解させます。
さきほどのStack Overflowの調査の数字を紹介したときも、「どの年の、どの調査の、どの質問への回答か」をできるだけ添えたつもりです。数字を使うなら、数字の出どころまで含めて責任を持つ。それが最低限の礼儀だと思っています。
物理学者のリチャード・ファインマンは、1974年のカリフォルニア工科大学の卒業式のスピーチ（「カーゴ・カルト・サイエンス」として知られています）で、こう語りました。
The first principle is that you must not fool yourself — and you are the easiest person to fool.
（第一の原則は、自分をだましてはいけない、ということだ。そして、いちばんだましやすいのは自分自身なのだ）
いい数字が出ると、人はつい、その数字を信じたくなります。自分で測った数字ならなおさらです。だからこそ、数字を出すときは、測り方と条件をセットで書きます。自分をだまさないために。そして、読む人をだまさないために。
約束3：引用するなら、出典を確かめる
これは、名言が好きな人間としての約束です。
インターネットには、有名人の言葉として広まっているけれど、本人が言ったという確かな記録がない「名言」がたくさんあります。
たとえば「6歳の子どもに説明できなければ、理解したとは言えない」という言葉。アインシュタインの名言としてよく紹介されますが、名言の出典を調べている英語サイト「Quote Investigator」などでも、本人の発言だという確かな記録は見つかっていないとされています。言っていることは素晴らしいのに、出典だけがふわふわしているのです。
技術記事でも同じことが起きます。「公式ドキュメントにこう書いてある」と書くなら、そのドキュメントへのリンクを貼る。「〇〇という調査では」と書くなら、その調査を自分で開いて確かめる。孫引きで済ませない。地味ですが、記事全体の信頼は、こういう地味なところで決まると思っています。
この記事に載せた引用も、出典を確かめたものだけを選びました。……と書いてしまった以上、もし間違いがあったら、遠慮なくコメントで教えてください。
約束4：「分からない」を、分からないまま書く
技術記事を書いていると、どうしても「全部分かっている人」のふりをしたくなります。でも、実際の開発は分からないことだらけです。原因は特定できたけれど、なぜそれで直るのかまでは分からない。ドキュメントにない挙動を見つけたけれど、それが仕様なのかバグなのか分からない。
そういうときは、分からないことは、分からないと書きます。 「ここから先は推測です」と明記したうえで、推測を書きます。
分からないことを正直に書いておくと、いいことがあります。それを知っている誰かが、コメントで教えてくれるかもしれないのです。三人寄れば文殊の知恵。Qiitaには、三人どころではない数のエンジニアがいます。
考えてみれば、これは「ほぼ正しい」AIと逆の振る舞いです。AIは、分からないときでも、それらしい答えを返してくれます。だからこそ人間の書く記事は、「ここは自信がある」「ここは分からない」の境目を、はっきり書いておくことに価値があるのだと思います。
約束5：間違いは、こっそり直さない
どれだけ気をつけていても、記事に間違いは混ざります。人間ですから。
間違いが見つかったときは、本文を黙って書き換えるのではなく、何を、いつ、なぜ直したのかを追記として残します。 コメントで指摘してくださった方がいれば、そのことも書きます。
チーム開発で、共有ブランチの履歴をgit push --forceで書き換えると嫌がられるのと同じです。履歴が残っていれば、以前の記事を読んで実装してしまった人が「あ、ここが変わったのか」と気づけます。記事の更新履歴は、書き手のためではなく、読み手のためのものです。
約束6：読む人の時間を、雑に扱わない
技術記事を読む人の多くは、何かに困って検索し、たどり着きます。つまり、急いでいます。
だから、記事の冒頭には「この記事で何が分かるのか」を書きます。結論がある記事は、結論を先に書きます。長い記事には見出しをきちんと付けます。前置きを長くしすぎない（この記事の前置きが「橋の日」から始まったことは、そっと棚に上げておきます）。
その一方で、情報を並べるだけの記事にもしたくありません。最後まで読んだ人が「読んでよかった」と思えるような、ちょっとした発見や、くすっと笑える一文を、どこかに忍ばせておきたい。急いでいる人には最短距離を、時間のある人には寄り道の楽しさを。欲張りですが、両方目指します。
約束7：続ける
最後の約束が、いちばん難しいと思っています。
技術ブログを始めて、3本書いて、そのまま止まる。エンジニアの「あるある」の中でも、かなり上位に入る話ではないでしょうか。最初の1本は勢いで書けます。でも、10本目、20本目を書き続けるのは、勢いだけでは無理です。
なので、「毎週必ず書く」といった、守れなかったときに心が折れる約束はしません。代わりに、書くハードルを下げます。 大作を書こうとしなくていい。仕事の中で「あ、これ前にもハマったな」と思ったら、それがネタです。3時間溶かしたバグは、立派な記事になります。
継続は力なり。千里の道も一歩から。言い古された言葉ですが、言い古されているのは、それだけ多くの人が実際に確かめてきたからだと思います。
ちなみに「千里の道も一歩から」の元になったのは、『老子』の「千里の行も足下より始まる」という一節だと言われています。英語では「A journey of a thousand miles begins with a single step.」。この記事が、その一歩目です。
ついでに決めた「書かないこと」
約束を7つも並べたら、優等生の作文みたいになってしまったので、裏側も見せておきます。「書くこと」を決めるのと同じくらい、「書かないこと」を決めておくのは大事だと思っています。仕様書でいえば、スコープ外の定義です。
触っていない技術の「〇選」記事は書かない。
「おすすめのベクトルDB 10選」のような記事は、読む側としては便利です。でも、10個すべてを本番で使い込んだ人は、たぶんほとんどいません。私も、自分で触って比べたもの以外は、並べて評価しないことにします。2つしか比べていないなら「2つを比べてみた」と書きます。タイトルは地味になりますが、そのぶん中身には責任を持てます。
他の技術を下げて、自分の技術を上げない。
「〇〇はもうオワコン」「まだ△△使ってるの？」といった言い回しは使いません。PHPは何度「オワコン」と言われたか分かりませんが、今日も世界中の膨大な数のサイトを、文句も言わずに動かし続けています。技術には向き不向きがあるだけで、上下はありません。その技術で今日も誰かがご飯を食べている、ということを忘れないようにしたいです。
誰かの成果を、自分の手柄のように書かない。
参考にした記事、ヒントをくれたドキュメント、助けてくれた人。記事の中身が誰かのおかげでできたものなら、そのことをきちんと書きます。オープンソースの世界がここまで来られたのは、こういうクレジットの文化があったからだと思っています。
お客さまの情報は、絶対に書かない。
仕事の経験をもとに記事を書くことは多くなると思います。でも、どの会社の、どのシステムの話なのかが分かるような書き方はしません。記事に出てくる事例は、本質を残したまま、架空の設定に置き換えます。技術記事は信頼で成り立っていて、守秘義務はその信頼のいちばん下にある土台です。
これから書いていくこと
約束と「書かないこと」を決めたところで、これからどんな記事を書いていくかも、ざっくり共有しておきます。夏休みの自由研究の計画表のようなものだと思って、気楽に眺めてください。
1. 生成AI・RAGの「現場の話」
いちばん書きたいのは、これです。RAGチャットボットは、作るだけなら数日でそれらしいものが動きます。でも、業務で使える精度まで持っていくのは、驚くほど泥くさい作業の積み重ねです。チャンキング、検索の工夫、評価の仕組み、権限管理。公式チュートリアルの「その先」にある話を、できるだけ具体的に書いていきます。
構想中なのが、**【RAG事件簿】**というシリーズです。RAGが間違った答えを出したとき、「LLMのせいだ」と決めつける前に疑うべき場所を、事件ファイル形式でまとめていく予定です。まさに「ほぼ正しいけれど、ちょっと違う」答えが、どこで生まれているのかを追いかける話になります。
2. Web開発の「地味だけど効く」話
Laravel、Next.js、WordPressなど、長く付き合ってきた技術についても書きます。最新の派手な機能よりも、「知っていれば3時間節約できる」ような地味な話を中心にするつもりです。WordPressの真っ白な画面と10年以上付き合ってきた人間にしか書けないことも、きっとあるはずなので。
3. 業務自動化とBotの話
Slack BotやLINE Botで業務を自動化する話も書きます。Botは、うまく作れば誰にも気づかれずに、毎日ひっそりと働き続けてくれる健気な存在です。その健気さを支える裏側の工夫について書いていきます。
4. エンジニアの「暮らし」の話
技術の話ばかりだと書くほうも息が詰まるので、ときどき、エンジニアの暮らしにまつわる話も書くつもりです。フリーランスとしての仕事の進め方、資格の勉強法、座りっぱなしの体との付き合い方、家の中の小さな困りごとをコードで解決した話など。技術記事の合間の、箸休めのような記事になればと思います。
……今日は「箸の日」でもあるので、この言葉はどうしても使いたかったのです。
おわりに：最初の橋脚を、ここに
アラン・ケイの有名な言葉があります。
The best way to predict the future is to invent it.
（未来を予測する最良の方法は、それを発明することだ）
AIがこの先、エンジニアの仕事をどう変えていくのか。正直、私にも分かりません。たぶん、誰にも分からないと思います。ただ、分からないなりに、目の前の問題を一つずつ解いて、その経緯を書き残していくことはできます。その積み重ねが、私なりの「未来の発明」の仕方なのだと思います。
橋は、いきなり向こう岸まで架かるわけではありません。まず川底に一本、橋脚を立てる。次の一本を立てる。そうやって少しずつ、向こう岸に近づいていきます。この記事は、その最初の一本です。
そして、この記事に書いた7つの約束は、仕様書です。仕様書は書いただけでは意味がなく、実装して、テストして、本当に仕様通りに動くかを確かめて、初めて価値が生まれます。ここから先の記事は、全部この仕様書のテストケースです。仕様に反する記事を見つけたら、遠慮なくバグ報告（コメント）をお願いします。ちゃんとissueとして受け止めて、追記で直します。
では、最初のコミットを。
$ git log --oneline --format="%h %ad %s" --date=format:"%Y-%m-%d (%a)"
c47ca75 2026-08-04 (Tue) Hello, Qiita: 7つの約束を仕様として定義
まだ1行しかないログですが、ここからどれだけ伸びていくのか、自分でも楽しみです。
次の記事では、さっそく現場の話をします。テーマは、「ほぼ正しい」答えの犯人探し。最初の事件現場で、お待ちしています。
最後まで読んでいただき、ありがとうございました。暑い日が続きますので、どうか水分補給を忘れずに。フォローしていただけると次の記事が届きますし、初投稿にいいねを一つ押していただけたら、それだけで次の記事を書く元気が出ます。