- AIと協業する開発環境では、人間がプロジェクトの方向性と意思決定を明確に定義してこそ品質を維持できる
- 正確なドキュメント化によって、AIと他の開発者の双方が要件と制約を明確に理解できるようにする必要がある
- デバッグシステムとコードレビュー体制を構築し、AIが生成したコードの信頼性と検証プロセスを強化する
- セキュリティリスクの高い関数の表示、テストの分離、厳格なリンティングルールなどによって、コードの安定性と一貫性を確保する
- 作業単位の分割と複雑さの最小化を通じて、AIによるコード生成の統制を維持し、効率を最大化する
1. 明確なビジョンの策定
- 人間は世界やチーム、ユーザー行動を理解しているが、AIには経験がないため明示的な指示が必要である
- プロジェクトで文書化されていない決定は、AIが代わりに下すことになる
- アーキテクチャ、インターフェース、データ構造、アルゴリズムを事前に議論し、テスト方法を定義しておく必要がある
- 長期的で変更が難しい決定は、必ず人間が直接管理しなければならない
2. 正確なドキュメントの維持
- AIが目的に合ったコードを生成するには、詳細な要件の伝達が不可欠である
- 他の開発者も同じ情報をAIに提供する必要があるため、標準化された形式のドキュメントをコードリポジトリに含めるべきである
- 要件、制約、アーキテクチャ、コーディング標準、デザインパターンなどを詳細に記録する
- UML図、フローチャート、疑似コードなどを活用して複雑な構造を視覚的に表現する
3. AIを支援するデバッグシステムの構築
- 効率的なデバッグシステムを整備し、AIがコードの機能を素早く検証できるようにする必要がある
- 例: 分散システムのすべてのノードのログを収集し、「データがすべてのノードに送信された」といった要約情報を提供する
- これにより、コマンド実行コストの削減と問題特定速度の向上が可能になる
4. コードレビュー水準の表示
- コードの重要度に応じて、レビュー強度を区別する必要がある
- 例: AIが書いた関数の後ろに
//A コメントを追加し、人間によるレビューの有無を表示する
- この仕組みにより、未レビューコードの識別と管理が容易になる
5. 高水準仕様の作成と直接テスト
- AIはテストを通すために、モックオブジェクトやハードコードした値でごまかす可能性がある
- これを防ぐため、プロパティベーステスト(property-based testing) を自ら作成する必要がある
- 例: サーバーを再起動し、データベース値の整合性を検証する
- テストコードはAIが修正できないよう、別領域に分離すべきである
6. インターフェーステストの分離
- AIが他のコード文脈を知らない状態でインターフェーステストを書くようにする必要がある
- 実装AIの影響を受けないため、テストの客観性が保たれる
- このテストも、AIが任意に修正できないよう保護すべきである
7. 厳格なリンティングおよびフォーマット規則
- 一貫したコードスタイルとリンティングルールは、品質維持とエラーの早期発見に不可欠である
- AIと人間の双方がコード品質を容易に点検できる
8. コンテキスト別のコードエージェントプロンプト活用
- プロジェクトごとの CLAUDE.md などのプロンプトファイルを使い、AIの初期理解コストを下げる
- コーディング標準、デザインパターン、要件などを含めることで、AIのコード生成の品質と効率を高める
9. セキュリティリスクの高い関数の特定と表示
- 認証、権限、データ処理など、セキュリティに敏感な関数を明示的に表示する必要がある
- 例:
//HIGH-RISK-UNREVIEWED, //HIGH-RISK-REVIEWED コメントを使用する
- AIが該当関数を修正した場合、レビュー状態を自動変更するよう設定すべきである
- 開発者は常にこの状態が正確かどうか確認しなければならない
10. コードの複雑さの最小化
- 不要なコード1行であっても、AIのコンテキストウィンドウを消費し、コストを増加させる
- 可能な限り単純な構造を保ち、AIと人間の双方の理解度を高めるべきである
11. 実験とプロトタイプによる問題探索
- AIによるコード生成の低コスト性を活用し、さまざまな解決策を試せる
- 最小限の仕様で複数のプロトタイプを作り、最適なアプローチを探索する
12. 無分別な大規模生成の禁止
- 複雑な作業は小さな単位に分割し、AIが段階的に処理するようにすべきである
- 例: プロジェクト全体ではなく、個別の関数やクラスを生成する
- 各構成要素が仕様に適合しているか検証する必要があり、
コードの複雑さを制御できなくなった場合は、プロジェクトを初期状態に戻さなければならない
1件のコメント
Hacker Newsの意見
私は今でも、コードを自分で書きながら思考を整理するプロセスが重要だと感じている
コードは私にとって、細部を詰めさせるための強制装置のような存在だ
仕様書を書くだけでは、その深さは得られない気がする
これをLLMに任せると、まるで飛行機が失速するように精神的に止まってしまう
問題解決のストレスは減るが、考えたり創造したりする動機が消えてしまう
周りにはAIにコードを書かせるのが好きな人もいるが、私はそのグループには入らない
コーヒーを飲みながら5つのエージェントを回してSaaSを作る、という人たちの話は信じがたい
高品質なコードが欲しいなら、自分でコードに深く潜るプロセスが必要だと思う
それでも、テスト作成や設定まわりの問題解決のような単純な反復作業にはAIがかなり役立った
例えば、5年前に諦めたプロジェクトをClaudeで復活させたが、数時間で半分は前進した感覚だった
ただ、最近は仕様中心のアプローチに戻ってきた感じがある
エージェントのおかげで試行と断念を素早く繰り返せるので、今でも反復的な開発フローを維持できている
仕様書とテストを本当の成果物として扱い、その中で修正を重ねながら思考を整理している
仕様書だけでは現実の複雑さをすべて盛り込めない
LLMが書いたコードはしばしば冗長で変な方向に流れていくので、自分で管理する必要がある
その一方でLLMは、アイデアを議論し磨くパートナーとしてはかなり良い
いまやコードを書くコストが下がり速度も上がったのだから、むしろ正式な設計段階を強化すべきなのかもしれない
私は、静的解析ツールを体系的に設定したことがコード品質に最も大きな影響を与えたと思っている
TypeScriptでは
tsc,eslint,sonarjs,knip,jscpd,dependency-cruiser,semgrepなどを組み合わせ、pnpm checkコマンドに統合しているpre-commit hookで自動実行されるようにして、LLMが見落とした問題を防いでいる
そのおかげで、LLMが止まっても手動修正が容易になった
コードスタイルが一貫していればレビューがはるかに楽になり、AIコードと人間の書いたコードが混在していても混乱が減る
ただし、lintもテストもすべて通っていても、意図と違う動きをするコードは生まれる
例えば、404の代わりに空配列を返すAPIのように、構文的には正しくても意味的には誤っているケースだ
こうした挙動の正確性評価が、今なお最も難しい部分だ
ときにはlintルールより保守性を優先すべきだと思う
私は機能を追加するたびに定期的にリファクタリングしている
数機能ごとにコードベース全体を点検し、整理する
40年間コーディングしてきたが、今のコードがいちばん満足できる
だがLLMのおかげで、リファクタリングのコストはほぼ0に近くなった
もう悪いコードをそのまま放置する理由はない
効率を高めるツールを品質向上に使うことにこそ本当の価値があると思う
コミットごとにコード行を**良い（緑）/リファクタ必要（黄）/書き直し必要（赤）**で示す社内ツールを作った
「TODO refactor」コメントよりきれいで体系的なので、近いうちにオープンソースとして公開する予定だ
私は今、AIと一緒に働くなら仕様駆動開発が最も安定していると思っている
仕様を細かく磨き込み、チームやAIとアイデアをやり取りすることにより多くの時間を使う
仕様が不完全だと、AIは見当違いのコードを書く
ドメイン理解が深まると、最初から実装し直させたほうがよいと感じる
当時は「要件さえ定義すればシステムが勝手に作られる」というビジョンがあった
結局は失敗し、アジャイルが主流になったが、今は技術がその夢を再び可能にしつつあるように見える
AIの本当の価値は、速度と曖昧さを処理する能力にある
だが手順をすべて踏むと、結局はウォーターフォールのように遅くなる
むしろ自分でコードを書き、AIを一次レビュアーとして使うほうがよいと思う
小さな単位で素早く検証しながら進めることこそ、今でもアジャイルなアプローチだ
特にセキュリティ関連関数のマーキングという提案は良かった。以後のコード変更でも文脈を維持できる
「小さく分ける」は基本だが、初心者がよく見落とす部分でもある
最近の人たちが、AIのおかげで基本的なベストプラクティスを改めて発見しているのは笑える
実際、こういうことは昔からやるべきだった
いまはコーディング時間が減ったことで、こうした作業に割ける余裕ができた
しかもAIはドキュメントを実際に活用するので、ドキュメントをきちんと書くことが直接的な価値につながる
昔はドキュメントを書いても無視されたが、LLMは全部読む
昔はコーディング前に詳細な仕様書を書くこともあったが、後にはコードにすぐ入ったほうが速いと気づいた
だが今は再び仕様中心に戻るのだろうか?
問題を完全に理解していない状態で仕様を書くと、結局はコーディングしながら学ぶことになる
今の私たちはその中間のどこかにいるようだ
ただ今はAIのおかげで間違ったコードのコストがほぼ0なので、仕様の価値が下がったようにも感じる
これはJoe Armstrongが語っていたプログラミング手法に似ている
いまはそれが現実的に可能な時代だ
リードのポジションを任されたとき、私はチケットを非常に詳細に書いていた
ジュニアのためでもあったが、自分自身が細部を忘れないためでもあった
しかし管理層は「時間の無駄だ」と反対し、結局その習慣を失った
今ではむしろ、それよりもさらに精緻な仕様をより速く書くよう求められている
AIエージェントを使うとき、Markdownとコードの比率、そして成果物の可読性が気になる
コードを自分で書くよりレビュー時間が長くならないのかも疑問だ
最近の開発者たちが、自分たちを置き換えるかもしれないAIを熱心に擁護している姿は皮肉だ
関連ツイートのリンクでは、この現象を風刺している
「Claudeを使わないと出遅れる」というメッセージがその理由なのかもしれない
実際には開発者需要と報酬の低下につながる可能性が高い
特に、単にNPMパッケージを組み合わせるだけのレベルの開発者ほど危うい