AI駆動開発でCursorやClaude Codeの精度が上がるTypeScript/Pythonの書き方
CursorやClaude Codeを使った開発では、コードの書き方によってAIの出力精度が大きく変わります。「型があるかどうか」「命名が一貫しているか」「プロジェクト構造が予測可能か」——これだけで、生成されるコードのクオリティが体感で変わります。
この記事では、AI駆動開発で精度が上がる具体的なコードの書き方を、TypeScriptとPythonそれぞれで整理します。
TypeScript：AIに読ませるための型の書き方
戻り値の型を明示する
// ❌ AIが戻り値の構造を推測するしかない
async function getUser(id: string) {
return fetch(`/api/users/${id}`).then(r => r.json());
}
// ✅ AIが戻り値を正確に把握できる
interface User {
id: string;
name: string;
email: string;
role: "admin" | "member";
}
async function getUser(id: string): Promise<User> {
const res = await fetch(`/api/users/${id}`);
return res.json() as User;
}
戻り値の型が明示されていると、「この関数の結果を使って〇〇を実装して」という指示に対して、AIが正しいプロパティ名でコードを生成できます。
Union型でドメインを表現する
// ❌ status が何を取るか不明
type Order = {
id: string;
status: string;
};
// ✅ 取りうる値が明確 → AIが正しい条件分岐を生成できる
type OrderStatus = "pending" | "processing" | "shipped" | "delivered" | "cancelled";
type Order = {
id: string;
status: OrderStatus;
};
string のままにしておくと、AIがテストコードや条件分岐を生成するときに「pending」「active」「done」など、実際に使っていない値を使ってしまいます。
Interface に JSDoc を一行添える
/** 注文明細1行分 */
interface OrderItem {
/** 商品ID（SKU） */
productId: string;
/** 注文数量（1以上） */
quantity: number;
/** 単価（税抜・円） */
unitPrice: number;
}
JSDoc はAIへのヒントとして機能します。「税抜」「1以上」のような制約をコメントに書いておくと、AIが生成するバリデーションロジックに反映されやすくなります。
tsconfig で strict を有効にする
{
"compilerOptions": {
"strict": true,
"noImplicitAny": true,
"strictNullChecks": true
}
}
strict モードを有効にすると、AIが生成するコードにも型チェックが通るコードを出す傾向が強まります。any だらけのコードを生成しなくなるのも副次的な効果です。
Python：型ヒントで精度を上げる
関数に型ヒントをつける（最低限これだけ）
# ❌ AIが引数・戻り値を推測するしかない
def create_invoice(order, customer):
...
# ✅ 型ヒントで意図が伝わる
from dataclasses import dataclass
@dataclass
class Order:
id: str
items: list["OrderItem"]
total: int # 税抜合計（円）
@dataclass
class Customer:
id: str
name: str
email: str
def create_invoice(order: Order, customer: Customer) -> dict[str, str]:
...
Pydantic で API の入出力を定義する
FastAPI + Pydantic の組み合わせは、AI駆動開発と特に相性がいいです。Pydanticモデルがあると、AIは「このエンドポイントに何を渡して何が返ってくるか」を正確に把握した上でコードを生成します。
from pydantic import BaseModel, EmailStr
from typing import Literal
class UserCreate(BaseModel):
name: str
email: EmailStr
role: Literal["admin", "member"] = "member"
class UserResponse(BaseModel):
id: str
name: str
email: str
role: Literal["admin", "member"]
created_at: str
pyproject.toml で型チェックツールを設定する
[tool.mypy]
strict = true
ignore_missing_imports = true
[tool.ruff]
select = ["E", "F", "UP", "ANN"] # ANN: 型アノテーション強制
mypy の strict モードを入れておくと、AIが生成したコードを貼ったときに型エラーがすぐ検出されます。Claude Codeと組み合わせる場合、claude --mcp でLSP診断情報をClaudeに渡すと、型エラーを自動で修正するループが回せます。
プロジェクト構造：AIが「どこに何を置くか」を理解できる設計
AIへの指示で「〇〇コンポーネントを追加して」「〇〇のAPIを実装して」と伝えたとき、プロジェクト構造が予測可能だとAIが正しい場所に正しいファイルを生成します。
Next.js（App Router）
src/
├── app/
│ ├── (dashboard)/
│ │ ├── orders/
│ │ │ ├── page.tsx # 一覧
│ │ │ └── [id]/page.tsx # 詳細
│ └── api/
│ └── orders/
│ └── route.ts
├── components/
│ ├── ui/ # shadcn/ui など汎用
│ └── orders/ # 注文ドメイン固有
├── lib/
│ ├── api/ # fetch ラッパー
│ └── utils/
└── types/
└── index.ts # 型定義の集約
types/index.ts に型を集約しておくと、「この型を使って〇〇を実装して」という指示が通りやすくなります。
FastAPI
app/
├── main.py
├── routers/
│ ├── orders.py
│ └── users.py
├── models/
│ ├── order.py # Pydantic モデル
│ └── user.py
├── services/
│ ├── order_service.py
│ └── user_service.py
└── core/
├── config.py
└── database.py
まとめ
AI駆動開発で精度を上げるために今日からできることをまとめます。
| 優先度 | やること |
|---|---|
| ★★★ | 関数の引数・戻り値に型をつける（TypeScript / Python 両方） |
| ★★★ |
strict モードを有効にする（tsconfig / mypy） |
| ★★ | Union型・Literal型でドメインを表現する |
| ★★ | Pydantic / interface でAPIの入出力を定義する |
| ★ | JSDoc / Docstring で制約・意図を一行添える |
| ★ | プロジェクト構造を予測可能なパターンに揃える |
型を書くことはAIのためだけでなく、コードの品質そのものを上げる習慣でもあります。AI駆動開発を導入しているチームはぜひ試してみてください。