見出し画像

【AI協働コーディング】AIに“自分のプロジェクト”をわからせる .mdファイルのレシピ

ikejunUI

週刊プレイグラウンズ 増刊37+号


第37号には、全コードだけでなく、二つの「.md」ファイルを用意しました。そこで、この増刊号では、少し脇道にそれて「.md（マークダウン）ファイル」の説明をします。

生成AIプログラミングをやっている人には当たり前のことかもしれません。でも、生成AIでコードを書き始めたばかりの人、自己流でなんとなくやっている人にとっては、「なぜコードだけじゃなく、説明書きみたいなファイルが付いてくるんだろう？」と思っているかもしれません。増刊号で、この「見えない一手間」を開いてお見せします。

1. .mdファイルって、そもそも何のためにあるの？

マークダウン（.md）は、見出しや箇条書きを簡単な記号で書ける、軽いテキスト形式です。ここまでは、ただの書式の話。

大事なのは中身のほうです。このシリーズで添えることにした.mdは、人間のための説明書ではなく、生成AIに渡す「文脈（コンテキスト）」です。

生成AIにコードを手伝ってもらうとき、多くの人はこう使っていると思います。「こういうコードを書いて」とお願いして、返ってきたコードを使う。それでも動くものはできます。

でも、AIはあなたのプロジェクトの事情・背景を知りません。どんな環境で動かすのか、過去にどんな失敗をして今の形になったのか、何を大事にしているのか。一般論で答えているだけです。

.mdファイルは、その「事情・背景」をまとめてAIに渡すためのレシピです。レシピを渡してから調理に取り組むのと、渡さずに取り組むのとでは、返ってくる答えが変わってきます。

2. このシリーズでは、2種類のレシピ(.md)を使い分けます

直近のシリーズ（〜第37号）では、役割の違う2つのレシピ（.md）を添えました。

プロジェクトの全コードと、二つのレシピ（.md）の例を、次の記事で入手できます。

  • wklyPGs_context37.md … 生成AI向けの文脈ファイル。「このプロジェクトはこういう目的で、こういう環境で、こういう約束事で作っている」をAIに伝えるためのもの。次に開発を手伝ってもらうAIが、前提を間違えないためのレシピです。

  • wklyPGs_reference37.md … 人間向けの技術リファレンス。調整用の数値がどこにあって、なぜその値なのか。自分で実際に動かして調整するときの手引きです。

読み手が違えば、書くべき中身も変わる。だから分けています。AIに渡すものと、自分が読むものは、別のファイルにしたほうがすっきりします。

（余談：ファイル名を「CLAUDE.md」にしているのを見かけることがあります。これは特定のAIツールが自動で読み込む決まりの名前で、中身が特定のAI専用というわけではありません。中身はどの生成AIに渡しても同じように役立ちます。このシリーズでは、そこが分かりやすいように中立的な名前にしました。）

3. あるとないとで、こんなに変わる（仮想の例で）

ここがいちばんお伝えしたいところです。同じお願いをしても、レシピ（.md）を渡すか渡さないかで、AIが書いてくるコードが変わります。2つ、分かりやすい例を挙げます。

なお、これはあくまで「こうなりやすい」という傾向の話です。生成AIの出力は毎回まったく同じにはならないので、必ずこうなると約束するものではありません。それでも、渡しておくと“いい方に転びやすくなる”のは確かです。

例A：SwiftUIのViewがあるのに、わざわざ古い書き方をしてしまう

「画面に共有ボタンを付けて、ファイルを保存・共有できるようにして」とお願いしたとします。

レシピ（.md）を渡さないと、AIはインターネット上に大量に残っている少し前の書き方に引き寄せられがちです。共有シートを出すのに、UIKitという一つ前の仕組みを持ち出して、それをSwiftUIに橋渡しする…と、何段も手間のかかるコードを書いてくることがあります。

// 少し前の書き方（動くけれど、手間が多い）
struct ActivityView: UIViewControllerRepresentable {
    let items: [Any]
    func makeUIViewController(context: Context) -> UIActivityViewController {
        UIActivityViewController(activityItems: items, applicationActivities: nil)
    }
    func updateUIViewController(_ vc: UIActivityViewController, context: Context) {}
}
// これを、状態を管理しながら sheet で出す…という追加のコードが必要

間違ってはいません。動きます。でも、今のSwiftUIには、もっと簡単な書き方が用意されています。

レシピ（.md）に「iOS 16以降を対象、SwiftUIのモダンな書き方を優先」と書いてあると、AIはこう書いてくれます。

// 今の書き方（一行で共有シートが出せる）
ShareLink(item: url) {
    Label("共有", systemImage: "square.and.arrow.up")
}

ShareLinkは、iOS 16（SwiftUI 4）から加わった、共有シート専用のビューです。それ以前は、たしかにUIKitをラップするしかありませんでした。だからネット上には古い書き方の記事がたくさん残っていて、AIは何も言わないとそちらに引っぱられることがあるのです。

例B：使わなくていい場面まで、UIKitを持ち出してしまう

もうひとつ。SwiftUIには最初からボタンやスライダー（Button、Slider、Toggle）が用意されています。ところが文脈がないと、AIはこうした部品まで、わざわざUIKitのUIButtonをSwiftUIに橋渡しして作ってしまうことがあります。

これも「間違いではないけれど、遠回り」の典型です。

面白いのは、橋渡し（UIViewRepresentable）が“正解”になる場面もあることです。週刊プレイグラウンズ第36・37号の視覚支援アプリのカメラプレビューは、SwiftUIに相当するビューがないので、UIKitを橋渡しするのが正しい。つまり、

  • カメラプレビュー → 橋渡しが正解（SwiftUIにないから）

  • ボタンやスライダー → SwiftUIネイティブが正解（最初からあるから）

という使い分けが大事なのです。レシピ（.md）に「SwiftUIネイティブを優先し、橋渡しは本当に必要な箇所だけ」と書いておくと、AIはこの線引きを守ってくれます。「新しければ偉い」ではなく、「適材適所を判断できるようになる」。これが文脈を渡すことの、いちばん本質的な効き目だと思います。

4. 自分で試して、育てていく

「正確なレシピ(.md)を最初から書かないといけないのか」と身構える必要はありません。むしろ逆です。

おすすめは、AIが間違えるたびに、一行ずつ書き足していくやり方です。

たとえばこのシリーズでは、「画面の左右の向き」をAIが何度も取り違えました。計算上は正しく見えるのに、実機で動かすと左右が逆になる。そのたびに直して、最後に.mdへ一行、「向きは実機で確認するまで正しいと決めつけない」と書き足しました。すると次からは、AIが同じ間違いをしにくくなります。

つまり.mdは、最初に完成させるものではなく、プロジェクトと一緒に育てていくメモです。失敗を一つ記録するたびに、次から同じ失敗を避けられる。自分のための、そしてAIのための、失敗の貯金箱のようなものです。

まずは、あなたのプロジェクトで一度でもAIが的外れなコードを出したら、その理由を一行、.mdに書いてみてください。それが最初の一歩です。

5. 続けると、何が変わるか

プロジェクトをまたいで、同じ.mdを渡し続けると、生成がだんだん安定してきます。毎回ゼロから説明し直さなくても、AIが前提を踏まえたところから始めてくれる。長く続けるプロジェクトほど、この効果は効いてきます。

ただ、正直に書いておきます。これは「必ずそうなる」という保証ではありません。生成AIの出力は毎回少しずつ変わる可能性があるので、同じ.mdを渡しても、たまに違う方向のコードが返ってくることはあります。期待できる、けれど100%確実ではない。 そこは割り切って、うまくいかなかったら.mdをまた一行育てる、というつもりで付き合うのが良いと思います。

これから

週刊プレイグラウンズでは今後、各号、もしくはシリーズごとに、その内容に沿った2種類の.md（AI向けの文脈ファイルと、人間向けの技術リファレンス）を添えて提供していきます。コードだけでなく、その裏にある「前提」も一緒に持ち帰ってもらえるように。

コードは、書いて終わりではありません。次にそのコードを触るとき ── 自分であれ、AIであれ ── に、前提が正しく引き継がれるかどうかで、その先の進みやすさが変わります。.mdは、その引き継ぎのための、小さいけれど確かな一手間です。

もしこの号で「ちょっと試してみようかな」と思ってもらえたら、それがいちばんうれしい成果です。

おわりに ── 応援について

このシリーズの記事も、コードも、添えている.mdファイルも、すべて無料で公開しています。これからも、そのつもりです。視覚サポートのための技術が、少しでも多くの人の手に届くように ── それがこの連載を続けている理由だからです。

そのうえで、もし記事が役に立った、続きを読んでみたいと感じてもらえたら、note のチップ（応援）で背中を押していただけると、とても励みになります。いただいた応援は、実機でのテストや、次の号の試行錯誤を続けていくための力になります。

もちろん、読んでいただくこと自体が、いちばんの応援です。ここまで目を通してくださって、ありがとうございました。次号でまたお会いしましょう。

いいなと思ったら応援しよう！