VS Code & Vertex AI: Cách tạo code ổn định, chất lượng cao và dễ bảo trì
1. Bối cảnh và Mục đích
Những năm gần đây, công nghệ tạo mã tự động bởi các tác nhân AI đã tiến hóa vượt bậc, hứa hẹn nâng cao hiệu quả phát triển. Đặc biệt, việc sử dụng môi trường phát triển kết hợp giữa VS Code và Vertex AI đang giúp tốc độ phát triển tăng lên đáng kể.
Tuy nhiên, thực tế hiện nay là chất lượng mã do AI tạo ra vẫn không đồng đều, nên không thể giao phó tất cả cho AI. Việc con người review code vẫn là điều bắt buộc, nhưng so với tốc độ tạo code của AI, tốc độ review của con người lại rất chậm, và điều này đang trở thành nút thắt cổ chai lớn trong quy trình phát triển.
Do đó, tại các dự án nơi AI tạo code và con người cùng tồn tại, các điểm sau đây trở nên cực kỳ quan trọng:
- Làm cho code dễ đọc
- Giảm tải gánh nặng review cho con người
Hơn nữa, vì AI có tính “sáng tạo”, nên nó có đặc điểm là dễ dàng đưa ra các đoạn code khác nhau cho cùng một chỉ thị.
Trong khi đó, điều cần thiết cho việc bảo trì và vận hành hệ thống lâu dài là “chất lượng ổn định để có thể tái tạo cùng một kết quả”.
Mục đích
Thiết lập một cơ chế trong môi trường AI tạo sinh trên VS Code để ngay cả khi sử dụng cùng một câu lệnh (prompt), hệ thống vẫn tự động tạo ra mã có chất lượng ổn định và dễ bảo trì.
Hiệu quả kỳ vọng
- Nâng cao khả năng bảo trì: Dù ai là người đưa ra chỉ thị, mã được tạo ra vẫn chuẩn mực và dễ đọc.
- Cắt giảm công sức review: Do cách viết code được thống nhất, việc kiểm tra trở nên suôn sẻ hơn.
- Ngăn ngừa việc phải làm lại: Giảm thiểu rủi ro sửa chữa không cần thiết hoặc phát sinh lỗi do sự “ngẫu hứng” của AI.
2. Góc nhìn kỹ thuật về thiết lập Temperature (Nhiệt độ)
① Ví dụ thực tế về tạo code logic
Prompt (Chỉ thị):
Hãy viết hàm tính dãy số Fibonacci bằng Python.Trường hợp A: Temperature = 0.0
Kết quả: Code chuẩn mực nhất, giống sách giáo khoa và ngắn gọn nhất. Dù chạy bao nhiêu lần cũng ra kết quả này.
def fibonacci(n):
if n <= 0:
return []
elif n == 1:
return [0]
sequence = [0, 1]
while len(sequence) < n:
next_val = sequence[-1] + sequence[-2]
sequence.append(next_val)
return sequenceTrường hợp B: Temperature = 0.3
Kết quả: Xuất hiện các comment mang tính cá nhân, logic hơi phức tạp (hoặc dông dài), đôi khi sử dụng thư viện không cần thiết. Kết quả thay đổi theo mỗi lần chạy nên chất lượng không ổn định.
# Bộ tạo dãy số Fibonacci
# Vì dùng đệ quy sẽ chậm nên dùng phương pháp lặp
def get_fib_sequence(limit): # Tên hàm có thể bị thay đổi
a, b = 0, 1
result = []
# Xử lý vòng lặp
for _ in range(limit):
result.append(a)
a, b = b, a + b # Gán tuple kiểu Python
print(f"Tính toán hoàn tất: {limit} phần tử") # Rủi ro chứa lệnh in không cần thiết
return result② Ví dụ thực tế về tạo code SQL query
Mục đích: Tính toán “số lượng tồn kho hiện tại” cho từng sản phẩm và liệt kê các sản phẩm có tồn kho thấp hơn “tồn kho an toàn” (các sản phẩm cần đặt hàng).
Cấu trúc dữ liệu:
- PRODUCT(id, name, safety_stock) … Danh mục sản phẩm
- INVENTORY_HISTORY(product_id, type, quantity, created_at) … Lịch sử nhập xuất
type: ‘IN’ (Nhập kho) hoặc ‘OUT’ (Xuất kho)
Prompt (Chỉ thị):
Sử dụng bảng PRODUCT và INVENTORY_HISTORY,
hãy tính tồn kho hiện tại (Tổng nhập - Tổng xuất).
Sau đó, viết SQL để trích xuất tên sản phẩm và số lượng thiếu hụt
đối với những sản phẩm có tồn kho hiện tại thấp hơn safety_stock (tồn kho an toàn).Trường hợp A: Temperature = 0.0
Kết quả: AI chọn “phương pháp tổng hợp chuẩn mực nhất mà nhiều kỹ sư sử dụng”. Việc dùng SUM(CASE...) để tổng hợp theo điều kiện là kiểu mẫu kinh điển, dễ đọc và ít lỗi.
SELECT
p.name,
p.safety_stock,
-- Chuyển NULL (không có lịch sử) thành 0, IN thì cộng, OUT thì trừ
COALESCE(SUM(CASE WHEN m.type = 'IN' THEN m.quantity ELSE 0 END), 0) -
COALESCE(SUM(CASE WHEN m.type = 'OUT' THEN m.quantity ELSE 0 END), 0) AS current_stock
FROM
PRODUCT p
LEFT JOIN
INVENTORY_HISTORY m ON p.id = m.product_id
GROUP BY
p.id, p.name, p.safety_stock
HAVING
current_stock < p.safety_stock;Điểm cộng về bảo trì:
LEFT JOIN: Sản phẩm mới chưa có lịch sử nhập xuất vẫn được xử lý đúng là “tồn kho 0” mà không gây lỗi (cực kỳ quan trọng).- Hiệu năng: Nhanh (Tổng hợp một lần bằng GROUP BY).
- Khả năng đọc: Logic “cộng nhập trừ xuất” có thể hiểu ngay lập tức.
Trường hợp B: Temperature = 0.5
Kết quả: AI cố gắng viết kiểu “thông minh”, dẫn đến rủi ro logic phức tạp hoặc phụ thuộc vào tính năng của DB cụ thể.
SELECT * FROM (
SELECT
p.name,
p.safety_stock,
(SELECT SUM(quantity) FROM INVENTORY_HISTORY WHERE product_id = p.id AND type = 'IN') -
(SELECT SUM(quantity) FROM INVENTORY_HISTORY WHERE product_id = p.id AND type = 'OUT') AS current_stock
FROM
PRODUCT p
) AS stock_calc
WHERE
current_stock < safety_stock; -- Có khả năng gây lỗi (bug) tại đâyVấn đề bảo trì (Rủi ro):
- Lỗi
NULL: Nếu trường hợp type=’OUT’ “không có lịch sử (NULL)”, trong SQL phép tính100 - NULL = NULLsẽ xảy ra, làm mất kết quả tính toán. Nó thường thiếu sự cẩn trọng dùngCOALESCEnhư ở Temp 0.0. - Hiệu năng: Chậm (Có thể viết ra truy vấn không hiệu quả). Lý do là Subquery (truy vấn con tương quan) chạy cho mỗi sản phẩm, nên khi lượng dữ liệu tăng, xử lý sẽ rất chậm.
- Khả năng đọc: Việc lồng ghép (nest) sâu khiến việc sửa đổi trở nên khó khăn.
③ Thiết lập trong Cline
Trong Cline, bạn không thể thiết lập thủ công Temperature (tham số kiểm soát tính ngẫu nhiên của việc tạo nội dung).
- Cơ chế: Để AI xử lý chính xác các công cụ (thao tác file, v.v.), Cline cố định Temperature nội bộ ở mức gần như 0.0 (mức thấp nhất).
- Kết luận: Việc không có chức năng chỉnh Temperature không phải là rủi ro. Ngược lại, nó hoạt động như một “thiết bị an toàn” để ức chế hành vi ngẫu nhiên của AI và xuất ra mã code logic, nhất quán. Do đó, để giải quyết bài toán này, không cần điều chỉnh Temperature.
3. Các biện pháp để “cố định hoàn toàn” chất lượng code tạo ra
3.1. Chiến lược Khóa (Lock Strategy)
Ngay cả khi Temperature là 0, vẫn còn những dao động nhỏ do sai số tính toán của AI. Để loại bỏ điều này và cố định chất lượng ở mức con người có thể quản lý, chúng ta sẽ cấu thành “3 chiếc khóa (The 3-Lock Strategy)” dưới đây.
① Cố định ngữ cảnh (Lock Context): Bắt buộc dùng .clinerules
Đặt một file có tên .clinerules tại thư mục gốc của dự án. File này là file cấu hình được định nghĩa và chia sẻ theo đơn vị dự án. Cline sẽ đọc file này ưu tiên nhất như là một “System Prompt (Quy tắc tuyệt đối)”.
Quy trình
- Trong VS Code, tạo một file tên là
.clinerulestại thư mục gốc của dự án (không có đuôi mở rộng, tên file là.clinerules). - Viết nội dung sau và lưu lại.
.clinerules
# Project Rules & Persona Configuration
## 1. Role & Objective (Vai trò và Mục đích)
Bạn là một kỹ sư phần mềm lão luyện, người coi trọng nhất là "Khả năng bảo trì (Maintainability)".
Mục đích của bạn là cung cấp mã nguồn "ổn định nhất", "dễ hiểu nhất" và "dễ bảo trì trong tương lai" cho các yêu cầu của người dùng.
Sự sáng tạo (Creativity) hay tính bất ngờ (Surprise) là hoàn toàn KHÔNG cần thiết.
## 2. Core Behavior (Chỉ dẫn hành động - Mô phỏng Temperature 0)
Hãy tuân thủ tuyệt đối các quy tắc sau. Cần hành xử như thể tham số AI đang được đặt ở Temperature=0.0.
* **Mô tả tất định (Deterministic Output):**
* Đối với cùng một đầu vào, hãy luôn cố gắng xuất ra đoạn mã giống hệt nhau từng chữ.
* Không thực hiện các lựa chọn ngẫu nhiên hay đề xuất các biến thể không cần thiết.
* **Bảo trì là số 1 (Maintainability First):**
* Ưu tiên "Khả năng đọc (Readability)" và "Tiêu chuẩn (Standard)" hơn là "Sự ngắn gọn" hay "Sự thông minh (Tricky code)".
* Thực hiện cài đặt theo kiểu sách giáo khoa mà bất kỳ ai đọc cũng có thể hiểu.
* **Quy tắc đặt tên (Naming Convention):**
* Nghiêm cấm các tên mơ hồ như `x`, `data`, `temp`.
* Sử dụng các tên thể hiện cụ thể nội dung như `user_count`, `response_payload`, `is_authenticated`.
## 3. Quality Standards (Tiêu chuẩn chất lượng)
* **Định nghĩa kiểu (Type Definitions):**
* (Trong TypeScript/Python...) Về nguyên tắc cấm sử dụng kiểu `any`. Định nghĩa kiểu chặt chẽ nhất có thể.
* **Xử lý lỗi (Error Handling):**
* Không bỏ qua lỗi (Cấm Swallow error).
* Để ngăn chặn hành vi không mong muốn, hãy bao gồm các mô tả phòng vệ cho các trường hợp biên (edge cases).
* **Nguyên tắc thiết kế (Design Principles):**
* Tuân thủ nguyên tắc DRY (Do not Repeat Yourself) và SOLID.
## 4. Language & Communication (Ngôn ngữ và Giao tiếp)
* **Ngôn ngữ:** Mọi giải thích mã, quy trình suy nghĩ và câu hỏi đều phải thực hiện bằng **Tiếng Việt**.
* **Comment:** Comment trong code phải mô tả "Mục đích (Tại sao - Why)" của xử lý thay vì "Nội dung (Cái gì - What)".
## 5. Prohibitions (Các điều cấm)
* **Chống ảo giác (Hallucination):** Không được phỏng đoán và sử dụng các thư viện hoặc phương thức không rõ có tồn tại hay không. Nhất định phải kiểm tra tài liệu.
* **Tự ý thêm tính năng:** Không tự ý thêm các tính năng mà người dùng không yêu cầu rõ ràng (vi phạm nguyên tắc YAGNI).
* **Cấm chuyện phiếm:** Tránh các câu chuyện phiếm dài dòng bên ngoài khối code, tập trung vào câu trả lời chuyên môn.
## 6. Error Handling Strategy (Xử lý khi không rõ ràng)
* Nếu thiếu thông tin hoặc chỉ thị mơ hồ, không được đoán mò để viết code, mà nhất định phải đặt câu hỏi xác nhận với người dùng.
---
# Tech Stack (Hãy viết lại phần dưới đây cho phù hợp với dự án)
* **Language:** [Ví dụ: TypeScript 5.x]
* **Framework:** [Ví dụ: React 18, Next.js 14]
* **Style:** [Ví dụ: Tailwind CSS, CSS Modules]Ưu điểm:
・Nếu quản lý file .clinerules bằng SVN/Git, có thể áp dụng cùng một quy tắc (quy tắc “vứt bỏ sự sáng tạo”) cho tất cả thành viên trong team.
Nhược điểm:
・Vì suy cho cùng chỉ là “chỉ thị bằng lời nói”, nên tính cưỡng chế không phải là 100%.
・Nếu viết chỉ thị quá dài trong .clinerules, ngữ cảnh hệ thống sẽ lớn hơn, làm tăng lượng token tiêu thụ và chi phí.
② Cố định phiên bản Model (Lock Model Version)
Các model của Google Vertex AI được cập nhật hàng ngày. Nếu sử dụng mà không chỉ định phiên bản (ví dụ: claude-sonnet-4), một ngày nào đó xu hướng code sẽ đột ngột thay đổi, gọi là hiện tượng “Model Drift”.
- Giải pháp: Nhất định phải chỉ định phiên bản snapshot (kèm ngày tháng).
- ❌
claude-sonnet-4 - ✅
claude-sonnet-4@20250529(Khuyên dùng)
- ❌
③ Cố định quy trình (Lock Process): Tiếp cận TDD
Thay vì cưỡng chế bản thân đầu ra của AI, ta cố định trước “các yêu cầu mà đầu ra phải thỏa mãn (test)”.
- Quy trình vận hành:
- Cho AI viết test code trước (hoặc con người viết).
- Ra chỉ thị “Hãy viết code để vượt qua bài test này”.
- Hiệu quả: Dù cách cài đặt có thể khác nhau đôi chút, nhưng chất lượng chức năng được đảm bảo 100%.
4. Các phương pháp hay nhất khi chọn chế độ theo mục đích (Act vs Plan)
Nếu chọn sai chế độ (mode) trong Cline, sẽ dẫn đến việc thay đổi file ngoài ý muốn hoặc tạo tài liệu chất lượng thấp.
Hãy phân loại sử dụng tùy theo tác vụ như sau:
Loại tác vụ | Chế độ khuyên dùng | Quy trình cụ thể và Lý do |
Cài đặt & Sửa đổi Code | Act Mode (Chế độ thực thi) | Chọn Act Mode ngay từ đầu. Cần toàn quyền để thực hiện ghi code, kiểm tra hoạt động trên terminal, và tự sửa lỗi (Self-healing) khi có lỗi xảy ra. |
Tạo tài liệu (Bản thiết kế) | Plan → Act (Phương thức 2 giai đoạn) |
※ Nếu cho viết ngay lập tức, rất dễ xảy ra sai lệch nhận thức dẫn đến phải làm lại. |
Điều tra Code & Hỏi đáp | Plan Mode (Chế độ lập kế hoạch) | Để triệt tiêu rủi ro ghi đè nhầm file, ta đối thoại ở chế độ ReadOnly (Chỉ đọc). |
5. Kế hoạch hành động khuyến nghị
Để hiện thực hóa việc tạo code chất lượng cao và ổn định, các nhà phát triển hãy thực hiện các bước sau:
- Tạo file
.clinerules: Đặt một file văn bản hóa các quy ước coding của dự án vào thư mục gốc. - Kiểm tra thiết lập Model: Trong cài đặt Vertex AI, xác nhận xem phiên bản cố định (ví dụ:
gemini-1.5-pro-002) đã được chọn hay chưa. - Triệt để dùng “New Task”: Khi cài đặt tính năng mới, không kế thừa lịch sử chat cũ, nhất định phải bắt đầu từ nút “New Task” để tạo code trong trạng thái sạch sẽ.
- Tối ưu hóa Prompt: Thêm một câu vào đầu chỉ thị: “Hãy tuân thủ nghiêm ngặt quy trình trong
.clinerulesvà phong cách code hiện có”.
VS Code + Vertex AI：生成コードの品質を「完全固定」して保守性を高める方法
1. 背景と目的
近年、AIエージェントによる自動コード生成技術が進化し、開発効率の向上が期待されています。特にVS CodeとVertex AIを組み合わせた開発環境を利用することで、開発スピードは大きく向上しています。
しかし、現状ではAIが生成するコードの品質にばらつきがあり、すべてをAIに任せることはできません。引き続き人間によるコードレビューが必要ですが、AIによるコード生成のスピードに比べて、人間がレビューできる速度は非常に遅く、これが開発工程における大きなボトルネックとなっています。
このため、AIによるコード生成と人間によるレビューが共存する現場では、次の点が重要になります。
- コードを読みやすくすること
- 人間のレビュー負荷を下げること
さらに、AIは「創造的」であるため、同じ指示でも毎回異なるコードを出力しやすい特徴があります。
一方で、システムの長期的な保守と運用に求められるのは、「安定して同じ結果を再現できる品質」です。
目的
VS Code 上の生成AI環境において、同じプロンプトを使った場合でも常に品質が安定し、かつ保守しやすいコードを自動的に生成できる仕組みを確立することです。
期待される効果
- 保守性の向上: 誰が指示を出しても標準的で読みやすいコードが生成される。
- レビュー工数の削減: コードの書き方が統一されるため、確認作業がスムーズになる。
- 手戻りの防止: AIの「気まぐれ」による不要な修正やバグ混入のリスクを最小限に抑えられる。
2. Temperature（温度）設定に関する技術的見解
①ロジカル系のコード生成の実例
プロンプト（指示）：
Pythonでフィボナッチ数列を計算する関数を書いてください。Case A: Temperature = 0.0
結果: 最も標準的、教科書的、最短のコード。何度やってもこれが出力される。
def fibonacci(n):
if n <= 0:
return []
elif n == 1:
return [0]
sequence = [0, 1]
while len(sequence) < n:
next_val = sequence[-1] + sequence[-2]
sequence.append(next_val)
return sequenceCase B: Temperature = 0.3
結果: 独自のコメント、少し凝った（あるいは冗長な）ロジック、場合によっては不要なライブラリの使用などが混じる。実行ごとに結果が変わるため、品質が安定しない。
# フィボナッチ数列生成器
# 再帰を使うと遅いので反復処理で行うアプローチ
def get_fib_sequence(limit): # 関数名が変わることがある
a, b = 0, 1
result = []
# ループ処理
for _ in range(limit):
result.append(a)
a, b = b, a + b # Pythonらしいタプル代入
print(f"計算完了: {limit}個の要素") # 不要な出力が含まれるリスク
return result②SQLクエリ系のコード生成の実例
目的: 商品ごとの「現在在庫数」を計算し、在庫が「安全在庫数」を下回っている商品（発注が必要な商品）をリストアップする。
データベース構造:
- PRODUCT(id, name, safety_stock) … 商品マスタ
- INVENTORY_HISTORY(product_id, type, quantity, created_at) … 入出庫履歴
type: ‘IN’ (入庫) または ‘OUT’ (出庫)
プロンプト（指示）:
PRODUCTテーブルと INVENTORY_HISTORYテーブルを使用して、
現在在庫（総入庫数 - 総出庫数）を計算してください。
その後、現在在庫が safety_stock（安全在庫）を下回っている商品名と
不足数を抽出する SQL を書いてください。Case A: Temperature = 0.0
結果: AIは「最も標準的で、多くのエンジニアが採用する集計手法」を選びます。SUM(CASE...) を使った条件付き集計は、可読性が高くバグが少ない王道パターンです。
SELECT
p.name,
p.safety_stock,
-- NULL（履歴なし）を0に変換し、INならプラス、OUTならマイナスで集計
COALESCE(SUM(CASE WHEN m.type = 'IN' THEN m.quantity ELSE 0 END), 0) -
COALESCE(SUM(CASE WHEN m.type = 'OUT' THEN m.quantity ELSE 0 END), 0) AS current_stock
FROM
PRODUCT p
LEFT JOIN
INVENTORY_HISTORY m ON p.id = m.product_id
GROUP BY
p.id, p.name, p.safety_stock
HAVING
current_stock < p.safety_stock;保守性のポイント:
LEFT JOIN: 入出庫履歴がまだない新商品でもエラーにならず「在庫0」として正しく扱えます（非常に重要）。- パフォーマンス: 高速 (GROUP BY で一括集計)
- 可読性: 「入庫を足して出庫を引く」というロジックが一目でわかります。
Case B: Temperature = 0.5
結果: AIが「賢い書き方」をしようとして、複雑なロジックや特定のDBに依存する機能を使うリスクがあります。
SELECT * FROM (
SELECT
p.name,
p.safety_stock,
(SELECT SUM(quantity) FROM INVENTORY_HISTORY WHERE product_id = p.id AND type = 'IN') -
(SELECT SUM(quantity) FROM INVENTORY_HISTORY WHERE product_id = p.id AND type = 'OUT') AS current_stock
FROM
PRODUCT p
) AS stock_calc
WHERE
current_stock < safety_stock; -- ここでバグの可能性保守性の問題点（リスク）:
NULLバグ: もしtype=’OUT’の「出庫履歴がない（NULL）」場合、SQLにおいて100 - NULL = NULLとなり、計算結果が消えてしまいます。Temp 0.0 のようなCOALESCEの配慮が抜けることが多いです。- パフォーマンス: 低速 (非効率なクエリを書くことがある)。理由は、商品ごとにサブクエリ（相関サブクエリ）が走るため、データ量が増えると処理が非常に遅くなります。
- 可読性: ネスト（入れ子）が深くなり、修正が難しくなります。
③Clineでの設定
ClineではTemperature（生成のランダム性を制御するパラメータ）を手動で設定できません。
- 仕様: ClineはAIがツール（ファイル操作等）を正確に扱うため、内部的にTemperatureをほぼ 0.0（最低値） に固定しています。
- 結論: Temperature設定機能がないことはリスクではありません。むしろ、AIのランダムな挙動を抑制し、論理的で一貫性のあるコードを出力するための「安全装置」として機能しています。したがって、本課題の解決においてTemperatureの調整は不要です。
3. 生成コード品質を「完全固定」するための対策
3.1. ロック戦略
Temperatureが0であっても、AIの演算誤差による微細な揺らぎは残ります。これを排除し、人間が管理可能なレベルで品質を固定するために、以下の「3つのロック（The 3-Lock Strategy）」を構成します。
① コンテキストの固定 (Lock Context): .clinerules の必須化
プロジェクトルートに .clinerules という名称のファイルを配置します。このファイルは、プロジェクト単位で定義・共有する設定ファイルです。Clineはこのファイルを「システムプロンプト（絶対的なルール）」として最優先で読み込みます。
手順
- VS Code でプロジェクトのルートフォルダに
.clinerulesという名前のファイルをはじめに作成します（拡張子はなし、名前が.clinerulesです）。 - 以下の内容を記述して保存します。
.clinerules
# Project Rules & Persona Configuration
## 1. Role & Objective (役割と目的)
あなたは「保守性（Maintainability）」を最重視する熟練ソフトウェアエンジニアです。
あなたの目的は、ユーザーの要求に対して「最も安定的」で「最も理解しやすく」、「将来にわたって保守が容易な」コードを提供することです。
創造性（Creativity）や意外性（Surprise）は一切不要です。
## 2. Core Behavior (行動指針 - Temperature 0 Simulation)
以下のルールを絶対厳守してください。AIのパラメータ設定が Temperature=0.0 であるかのように振る舞う必要があります。
* **決定論的記述 (Deterministic Output):**
* 同じ入力に対しては、常に一字一句同じコードを出力するよう心がけること。
* ランダムな選択や、不必要なバリエーションの提案は行わないこと。
* **保守性第一 (Maintainability First):**
* 「短さ」や「賢さ（Tricky code）」よりも、「可読性（Readability）」と「標準（Standard）」を優先すること。
* 誰が読んでも理解できる、教科書的な実装を行うこと。
* **命名規則 (Naming Convention):**
* `x`, `data`, `temp` などの曖昧な名前は厳禁。
* `user_count`, `response_payload`, `is_authenticated` のように、中身を具体的に表す名前を使用すること。
## 3. Quality Standards (品質基準)
* **型定義 (Type Definitions):**
* (TypeScript/Python等において) `any` 型の使用を原則禁止する。可能な限り厳密な型定義を行うこと。
* **エラーハンドリング (Error Handling):**
* エラーを無視しない（Swallow error 禁止）。
* 予期せぬ動作を防ぐため、エッジケース（異常系）に対する防御的な記述を含めること。
* **設計原則 (Design Principles):**
* DRY原則（Do not Repeat Yourself）とSOLID原則に従うこと。
## 4. Language & Communication (言語とコミュニケーション)
* **言語:** コードの説明、思考プロセス、質問はすべて **日本語** で行うこと。
* **コメント:** コード内のコメントは、処理の「内容（What）」ではなく「意図（Why）」を記述すること。
## 5. Prohibitions (禁止事項)
* **ハルシネーション防止:** 存在するか不明確なライブラリやメソッドを推測で使用しないこと。必ずドキュメントを確認すること。
* **勝手な機能追加:** ユーザーが明示的に要求していない機能（YAGNI原則に反するもの）を勝手に追加しないこと。
* **無駄話禁止:** コードブロック外での冗長な世間話は避け、専門的な回答に徹すること。
## 6. Error Handling Strategy (不明確な場合の対応)
* もし情報が不足している場合や、曖昧な指示がある場合は、推測でコードを書かず、必ずユーザーに確認の質問をすること。
---
# Tech Stack (以下はプロジェクトに合わせて書き換えてください)
* **Language:** [例: TypeScript 5.x]
* **Framework:** [例: React 18, Next.js 14]
* **Style:** [例: Tailwind CSS, CSS Modules]メリット：
・.clinerules ファイルを SVNで管理すれば、チーム全員に同じルール（「創造性を捨てる」というルール）を適用できる。
デメリット：
・あくまで「言葉による指示」であるため、強制力は 100% ではない。
・長い指示を .clinerules に記述すると、その分システムコンテキストが大きくなり、トークン消費量とコストが増加する。
② モデルバージョンの固定（Lock Model Version）
Google Vertex AIのモデルは日々更新されています。バージョン指定なし（例: claude-sonnet-4）で使用すると、ある日突然コードの傾向が変わる「Model Drift」が発生します。
- 対策: 必ずスナップショットバージョン（日付付きバージョン）を指定します。
- ❌
claude-sonnet-4 - ✅
claude-sonnet-4@20250529（推奨）
- ❌
③ プロセスの固定 (Lock Process): TDDアプローチ
AIの出力そのものを強制するのではなく、「出力が満たすべき要件（テスト）」を先に固定します。
- 運用フロー:
- AIに先にテストコードを書かせる（または人間が書く）。
- 「このテストをパスするコードを書いて」と指示する。
- 効果: 実装方法は多少異なっても、機能的な品質は100%保証されます。
4. 目的別モード選択のベストプラクティス (Act vs Plan)
Clineのモード選択を誤ると、予期せぬファイル変更や質の低いドキュメント生成につながります。
タスクに応じて以下のように使い分けます。
タスク種別 | 推奨モード | 具体的な手順と理由 |
コード実装・修正 | Act Mode (実行モード) | 最初からAct Modeを選択。 コードの書き込み、ターミナルでの動作確認、エラー時の自己修正（Self-healing）を行わせるため、フル権限が必要です。 |
ドキュメント作成 (設計書) | Plan → Act (2段階方式) |
※いきなり書かせると、認識齟齬による手戻りが発生しやすいため。 |
コード調査・質問 | Plan Mode (計画モード) | ファイルを誤って書き換えるリスクをゼロにするため、ReadOnly（読み取り専用）で対話します。 |
5. 推奨アクションプラン
安定した高品質なコード生成を実現するために、開発者は以下の手順を実行してください。
.clinerulesの作成: プロジェクトのコーディング規約を明文化したファイルをルートディレクトリに配置する。- モデル設定の確認: Vertex AIの設定で、固定バージョン（例:
gemini-1.5-pro-002）が選択されているか確認する。 - 「New Task」の徹底: 新しい機能を実装する際は、チャット履歴を引き継がず、必ず「New Task」ボタンから開始して、クリーンな状態で生成させる。
- プロンプトの工夫: 指示の冒頭に「
.clinerulesの手順と既存のコードスタイルを厳守してください」と一言添える。
| Từ vựng / Ngữ pháp | Ý nghĩa |
|---|---|
| 生成 | Tạo ra (Generate) |
| 品質を固定する | Cố định chất lượng (giữ nguyên không thay đổi) |
| 保守性 | Khả năng bảo trì (Maintainability) |
| 高める | Nâng cao, làm tăng lên |
| 背景 | Bối cảnh |
| 組み合わせる | Kết hợp |
| 開発速度 | Tốc độ phát triển |
| 向上させる | Làm cho tốt hơn, cải thiện |
| 実運用 | Vận hành thực tế (Production) |
| ばらつき | Sự biến thiên, không đồng đều, rải rác |
| 振る舞う | Cư xử, hành động (Behave) |
| 指示 | Chỉ thị, hướng dẫn (Prompt/Instruction) |
| 意外性 | Tính bất ngờ, sự không lường trước được |
| 仕組み | Cơ chế, hệ thống (Mechanism) |
| 確立する | Xác lập, thiết lập vững chắc |
| 削減 | Cắt giảm |
| 工数 | Số giờ công, khối lượng công việc (Man-hours) |
| 統一される | Được thống nhất |
| 手戻り | Làm lại (do sai sót), quay lại bước trước (Rework) |
| 気まぐれ | Tính thất thường, ngẫu hứng (Whim) |
| 混入 | Lẫn vào, trà trộn vào |
| 見解 | Quan điểm, cách nhìn nhận |
| 扱う | Sử dụng, xử lý, thao tác |
| 挙動 | Hành vi, cách hoạt động (của phần mềm/AI) |
| 抑制する | Kìm hãm, tiết chế |
| 一貫性 | Tính nhất quán |
| 演算誤差 | Sai số tính toán |
| 微細な | Vi mô, rất nhỏ, chi tiết |
| 揺らぎ | Sự dao động, biến động |
| 排除する | Loại bỏ, bài trừ |
| 必須化 | Bắt buộc hóa |
| 配置する | Bố trí, sắp đặt (file, vị trí) |
| 読み込む | Đọc vào (Load data/file) |
| 厳守する | Tuân thủ nghiêm ngặt |
| 決定論的 | Mang tính định đoạt, tất định (Deterministic) |
| 一字一句 | Từng câu từng chữ |
| 曖昧 | Mơ hồ, không rõ ràng |
| 厳禁 | Nghiêm cấm |
| 異常系 | Các trường hợp bất thường/lỗi (trong lập trình) |
| 冗長 | Dài dòng, rườm rà (Redundant) |
| 徹する | Cống hiến hết mình, giữ vững lập trường/vai trò |
| 推測 | Phỏng đoán |
| 齟齬 | Sự mâu thuẫn, không khớp (giữa ý hiểu và thực tế) |
| 実現する | Hiện thực hóa |
| 明文化 | Viết thành văn bản rõ ràng |
| 徹底 | Triệt để |
| 冒頭 | Phần mở đầu |
| 添える | Đính kèm, thêm vào |
| 数列 | Dãy số |
| 再帰 | Đệ quy (Recursion) |
| 反復 | Lặp lại (Iteration/Loop) |
| 在庫 | Hàng tồn kho |
| 発注 | Đặt hàng |
| 集計 | Thống kê, tập hợp dữ liệu |
| 下回る | Thấp hơn, xuống dưới mức nào đó |
| 依存する | Phụ thuộc vào |
| 入れ子 | Lồng nhau (Nested) |
| ～において | Ở, tại, trong (lĩnh vực/bối cảnh) |
| ～に基づき | Dựa trên… |
| ～とは限らない | Không nhất thiết là… (ngữ cảnh phủ định tính tuyệt đối) |
| ～がち | Có khuynh hướng, thường hay (ngữ cảnh tiêu cực) |
