AI駆動 開発の 設計思想 Tư duy thiết kế phát triển AI
「何でも知っている AI 開発者」を作るのではなく、専門性を持ったエージェント群を編成し、文脈を制御する設計。Tinhvan Japan が現場で培った実装知から導いた答えである。 Thay vì xây dựng "một AI biết tuốt", framework này tổ chức đội ngũ agent chuyên môn hoá và kiểm soát context theo từng lĩnh vực — đáp án Tinhvan Japan rút ra từ thực tiễn triển khai.
全体の 流れ と関係性 Dòng chảy và mối liên hệ tổng thể
知識基盤(Layer 1)を整え、それを材料としてマルチエージェント体制(Layer 2)が稼働する。エージェントは作業中に得た知見を知識基盤へ書き戻し、人間は最終判断と方針決定を握る。 Trước tiên, dựng nền tri thức (Layer 1). Đội ngũ multi-agent (Layer 2) sau đó vận hành dựa trên nguyên liệu đó. Trong quá trình làm việc, các agent ghi ngược tri thức học được về nền tri thức; con người giữ vai trò quyết định cuối cùng và định hướng tổng thể.
人間が 必ず 関与する Con người bắt buộc phải tham gia
AIエージェントが自律的に動く範囲を広げても、重要な判断、承認、最終責任は人間が握るという原則。AI は提案・実装・検証までを担うが、リリース可否、設計上のトレードオフ、業務上のリスク受容、コンプライアンス判断は人間が決める。 Dù phạm vi AI tự chủ được mở rộng đến đâu, nguyên tắc cốt lõi vẫn là: quyết định quan trọng, phê duyệt và trách nhiệm cuối cùng phải thuộc về con người. AI đảm nhận phần đề xuất, hiện thực và kiểm chứng — còn việc duyệt release, đánh đổi thiết kế, chấp nhận rủi ro nghiệp vụ và phán quyết tuân thủ đều do con người quyết định.
明確で構造化された Input Input rõ ràng và có cấu trúc
曖昧なプロンプトは曖昧な結果を生む。要件、文脈、制約は明示的かつ整然と提供する必要がある。 Prompt mơ hồ sẽ cho ra kết quả mơ hồ. Yêu cầu, context và ràng buộc phải được trình bày rõ ràng, có cấu trúc.
判断と決定権 Phán đoán & Quyền quyết định
AIは提案する、人間が決める。重要な設計、トレードオフ、リスク判断は人間が握る。 AI đưa ra đề xuất, con người ra quyết định. Các vấn đề về thiết kế quan trọng, đánh đổi và đánh giá rủi ro phải do con người nắm giữ.
フィードバック & 継続レビュー Phản hồi & Review liên tục
スキルとワークフローは、人間が AI 出力を能動的にレビューし修正を還流させて初めて改善される。 Skill và workflow chỉ thực sự được cải thiện khi con người chủ động review output của AI và đưa các chỉnh sửa quay ngược về hệ thống.
クロスファンクショナルな連携 Phối hợp đa chức năng
AI-DLC は Dev / QA / BA / Ops を横断する。人間が部門を超えて調整する役割を担う。 AI-DLC trải dài qua Dev / QA / BA / Ops. Con người đóng vai trò điều phối, kết nối giữa các bộ phận.
専用ツールで 知識基盤 を築く Dựng nền tri thức bằng công cụ chuyên biệt
AIに渡す前に、人間が理解できる形で体系化する。スペック、コード、アーキテクチャ、決定の経緯まで、それぞれに適したフォーマットで整える。 Trước khi đưa cho AI xử lý, mọi thứ phải được hệ thống hoá theo cách con người hiểu được. Từ spec, mã nguồn, kiến trúc cho đến lý do đằng sau các quyết định — mỗi loại đều có định dạng phù hợp riêng.
仕様 & 業務知識Spec & Business
各種ドキュメントをAIが扱える形式へ正規化する。Chuẩn hoá tài liệu đa dạng về dạng AI có thể đọc.
コードグラフGraph Context
関数・モジュール・呼出関係をグラフ化し、文脈を圧縮する。Đồ thị hoá hàm, module, quan hệ gọi — nén context.
アーキテクチャ図Architecture & Flow
システム構造をコードで管理し、版を追えるようにする。Quản lý cấu trúc hệ thống bằng code, theo được phiên bản.
規約 & ルールファイルCoding Standards & Rules
AGENTS.md / CLAUDE.md でAIが守るべきルールを明文化する。曖昧な暗黙知を残さない。Văn bản hoá luật AI phải tuân bằng AGENTS.md / CLAUDE.md — không để tri thức ngầm tồn tại.
意思決定の記録Historical Decisions
「なぜそう決めたか」をADRで残す。技術選定の背景と業務上の制約をAIが参照できる形に。Ghi lại "vì sao quyết định như vậy" qua ADR. Bối cảnh chọn công nghệ và ràng buộc nghiệp vụ — để AI tra cứu được.
API & スキーマAPI & Schema
OpenAPI、GraphQL、DBスキーマを正としてAIに渡す。インターフェース定義こそが最も信頼できる文脈。OpenAPI, GraphQL, DB schema làm nguồn chính cho AI. Định nghĩa interface là context đáng tin nhất.
依存関係 & 影響分析Dependency & Impact
変更が何処に波及するかをナレッジグラフ上で可視化し、修正の安全性を担保する。Trực quan hoá ảnh hưởng của thay đổi trên knowledge graph — đảm bảo an toàn khi sửa.
Knowledge Foundation: ツール Knowledge Foundation: Bộ công cụ
知識抽出を高速かつ確実にする推奨ツール Bộ công cụ giúp trích xuất tri thức nhanh và đáng tin cậy
ブラウザ上でインタラクティブなグラフを構築。コードQ&A用の Graph RAG エージェント機能を搭載。 Dựng knowledge graph tương tác trực tiếp trong browser. Tích hợp Graph RAG agent cho Q&A code.
ニッチな JS lib、独自 DSL、COBOL、Delphi は tree-sitter パーサを手動で書く必要あり。JS lib hiếm, DSL custom, COBOL, Delphi cần tree-sitter parser thủ công.
任意のコードベースをインタラクティブな知識グラフに変換。マルチプラットフォーム対応。 Biến mọi codebase thành knowledge graph tương tác. Hỗ trợ đa nền tảng.
/understand-anything コマンドで関係性と呼出チェーンを検索。 Tìm quan hệ và call chain qua lệnh /understand-anything.
↗ github.com/Lum1104/Understand-AnythingMicrosoft 製の PDF/DOCX/PPTX → Markdown 変換ツール。AI コンテキスト構築に必須。 Tool của Microsoft chuyển PDF/DOCX/PPTX → Markdown. Cần thiết để dựng AI context.
日本語エンコーディング (Shift-JIS)、ふりがな除去、文書構造のアダプタが必要。Cần adapter cho encoding Nhật (Shift-JIS), bỏ furigana, cấu trúc doc.
Mitchell Hashimoto が Ghostty プロジェクトで広めた標準ファイル。「何処に何がある」を約100行に絞り、本体知識は docs/ 配下へ。コンテキストは希少資源。OpenAI のCodex 100万行実証でも採用された。 File chuẩn được Mitchell Hashimoto phổ biến qua dự án Ghostty. Gói gọn "ở đâu có gì" trong khoảng 100 dòng, tri thức chi tiết để dưới thư mục docs/. Context là tài nguyên khan hiếm. OpenAI cũng áp dụng cách này trong thử nghiệm 1 triệu dòng code với Codex.
- プロジェクト構造のマップ
- ビルド・テストコマンド
- コーディング規約の要点
- 過去の失敗パターン (アンチパターン)
- 詳細は docs/ への参照ポインタ
- Bản đồ cấu trúc dự án
- Các lệnh build & test
- Các điểm chính trong quy ước code
- Anti-pattern — những lỗi đã từng mắc
- Con trỏ tới docs/ để xem chi tiết
Claude Code がセッション開始時に常に読み込むファイル。AGENTS.md と同じく目次型で書くのが原則。詳細手順は .claude/skills/ 配下の SKILL.md へ遅延読み込みさせる構造に。 File mà Claude Code luôn đọc khi mở session. Cũng theo phong cách mục lục như AGENTS.md. Quy trình chi tiết được nạp trễ (deferred load) qua các file SKILL.md nằm trong .claude/skills/.
- 常に守るべき原則(短く)
- 主要ファイル・ディレクトリへのマップ
- 使用すべきコマンド・スクリプト
- 禁止事項と境界条件
- .claude/skills/ への参照
- Nguyên tắc cần luôn tuân thủ (ngắn gọn)
- Bản đồ các file & thư mục chính
- Các lệnh và script nên dùng
- Điều cấm và ràng buộc biên
- Tham chiếu tới .claude/skills/
プロジェクト構造Cấu trúc dự án
全フォルダツリー — 各ファイルの役割を解説。クリックで展開/折りたたみ。Toàn bộ cây thư mục — vai trò từng file. Click để mở/đóng từng cấp.
▶
project-root/
▶
.claude/
▶
docs/
▶
requirements/Always
PRDファイル — 1機能/1エピックにつき1ファイルFile PRD — mỗi feature/epic một file
▶
architecture/
▶
decisions/Always
ADR — 承認後は不変ADR — bất biến sau khi duyệt
▶
api-contracts/On-demand
ドメイン毎のAPIスキーマAPI schema theo từng domain
▶
tasks/
▶
active/Manual
現スプリント — AIセッションログSprint hiện tại — log session AI
▶
done/Manual
完了後に移動 — 履歴参照用Move sau khi merge — lưu lịch sử
▶
context/On-demand
AI 特化の長期記憶Tri thức dài hạn cho AI
▶
templates/Manual
新規ファイル用コピペ雛形Mẫu copy-paste cho file mới
▶
src/
専門特化 したマルチエージェント Multi-agent chuyên môn hoá
各エージェントは担当領域に特化したスキルとコマンドで動く。Tinhvan Japan がプロジェクトで蓄積したナレッジが、そのスキルセットの核となる。 Mỗi agent vận hành bằng bộ skill và command chuyên biệt theo lĩnh vực. Tri thức mà Tinhvan Japan tích luỹ qua các dự án chính là phần lõi của những bộ skill này.
業務エージェントBusiness Agent
要件と業務ロジックを読み解く。顧客側の言語で課題を整理し、技術側へ橋渡しする。Đọc hiểu yêu cầu và logic nghiệp vụ. Sắp xếp vấn đề theo ngôn ngữ của khách hàng, làm cầu nối sang phía kỹ thuật.
アーキテクトエージェントArchitect Agent
システム構造と技術選定を担う。ADRと既存アーキテクチャを参照し、整合性のある設計を提示。Phụ trách cấu trúc hệ thống và lựa chọn công nghệ. Tham chiếu ADR và kiến trúc hiện hữu để đưa ra thiết kế nhất quán.
開発エージェント群Development Agents
実装を担う複数の専門エージェント。フロント、バック、インフラ等を分担し、それぞれのスキルで作業する。Nhóm các agent chuyên môn phụ trách phần hiện thực. Chia thành front-end, back-end, infra... — mỗi agent dùng bộ skill riêng để xử lý phần việc của mình.
品質・セキュリティQA & Security Agents
テストケース生成、脆弱性検査、セキュリティルールの自動適用までを引き受ける。Đảm nhận toàn bộ: sinh test case, quét lỗ hổng bảo mật, tự động áp dụng các quy tắc bảo mật.
レビュアーエージェントReviewer Agent
コーディング規約と設計意図に照らして他エージェントの成果物を点検。人によるレビュー前の一次防波堤。Soi xét sản phẩm của các agent khác theo quy ước code và ý đồ thiết kế. Lớp chắn đầu tiên trước khi con người review.
ドキュメントエージェントDocumentation Agent
仕様変更、ADR、APIスキーマを実装と同期し、知識基盤を腐らせない役割を担う。Đồng bộ thay đổi spec, ADR và API schema với phần hiện thực — đảm bảo nền tri thức không bị lỗi thời theo thời gian.
Agent = Model + Harness
"Harness" は馬具・装着具を意味する。強力だが放っておくと暴走する馬 (LLM) を、有用な方向に働かせるための装着物 — それがハーネスである。Mitchell Hashimoto (Terraform 創業者) が命名し、OpenAI が 2026年2月に提唱した、AI時代の新しいエンジニアリング規律。 "Harness" có nghĩa là bộ yên cương — dụng cụ buộc lên con ngựa mạnh mẽ (LLM) nhưng nếu để mặc thì sẽ chạy loạn, giúp nó đi đúng hướng. Thuật ngữ do Mitchell Hashimoto (đồng sáng lập Terraform) đặt tên và OpenAI chính thức đề xuất vào tháng 2/2026 — một kỷ luật kỹ thuật mới cho thời đại AI.
ルールファイル × フィードバックループ × コンテキスト管理 Rule File × Feedback Loop × Context Management
ハーネスの基本は 3 つの要素で構成される。Martin Fowler の解説によると、これらの要素を整えることで AI エージェントの出力品質が劇的に向上する。 Nền tảng của Harness gồm 3 yếu tố cấu thành. Theo phân tích của Martin Fowler, khi triển khai đầy đủ cả 3 yếu tố này, chất lượng output của AI agent sẽ được nâng lên một cách đột phá.
AIエージェントが守るべきコーディング規約、命名規則、禁止事項を明文化したドキュメント。プロジェクトルートに .claude/rules.md や CONTRIBUTING.md を配置し、AIに読ませることで、一貫性のあるコードを生成させることができる。
Tài liệu văn bản hoá các quy ước code, quy tắc đặt tên và điều cấm mà AI agent phải tuân thủ. Đặt .claude/rules.md hoặc CONTRIBUTING.md ở thư mục gốc dự án và cho AI đọc — kết quả là AI sẽ sinh code nhất quán.
Mitchell Hashimoto が Ghostty で公開している AGENTS.md は、ハーネス設計の実例として広く参照されている。プロジェクト構造、ビルド・テストコマンド、コーディング規約、AIが過去に繰り返した間違いのアンチパターンリストが記載され、AIが同じミスを二度としないための「学習ノート」として機能する。
AGENTS.md mà Mitchell Hashimoto công khai trong dự án Ghostty hiện được tham chiếu rộng rãi như một ví dụ điển hình. File này chứa cấu trúc dự án, lệnh build/test, quy ước code và danh sách các anti-pattern mà AI từng mắc — hoạt động như "sổ tay học bài" giúp AI không lặp lại cùng một lỗi.
AGENTS.md CLAUDE.md .claude/rules.md RULES.md per module
AIの出力をテスト・検証し、失敗を検出して再試行させる仕組み。CI/CDパイプライン、自動テスト、静的解析ツールを組み込み、AIが生成したコードが品質基準を満たしているかを自動でチェックする。 Cơ chế test và kiểm chứng output của AI, tự động phát hiện lỗi và buộc AI retry. Tích hợp CI/CD pipeline, automated test và static analysis để tự động kiểm tra xem code AI sinh ra có đạt tiêu chuẩn chất lượng hay không.
OpenAI の実験では、約 1,500 件のプルリクエストが自動で生成・マージされたが、その裏では強固なフィードバックループが機能していた。テストが失敗すれば、AIは自動的にエラーメッセージを読み取り、修正を試みる。静的解析でコーディング規約違反が検出されれば、ルールファイルを参照して再生成する。このサイクルを高速で回すことで、人間の手を介さずに高品質なコードが生成される。 Trong thực nghiệm của OpenAI, khoảng 1.500 pull request đã được tự động sinh và merge — phía sau là một feedback loop mạnh mẽ đang vận hành. Khi test fail, AI tự động đọc thông báo lỗi và sửa lại. Khi static analysis phát hiện vi phạm quy ước, AI tham chiếu rule file và sinh lại code. Vòng lặp này quay tốc độ cao và sinh ra code chất lượng cao mà không cần con người can thiệp.
CI/CD PreToolUse Hooks PostToolUse Hooks Linter Type-check
AIが正しく判断するための情報を適切に提供すること。プロジェクト構造、依存関係、過去の決定事項、アーキテクチャドキュメントを整理し、AIが「なぜこのコードがここにあるのか」を理解できるようにする。 Cung cấp thông tin phù hợp để AI có thể phán đoán đúng. Sắp xếp cấu trúc dự án, quan hệ phụ thuộc, các quyết định trong quá khứ và tài liệu kiến trúc — để AI hiểu được "vì sao đoạn code này nằm ở đây".
OpenAI の研究によると、「Codex に地図を渡せ、1,000 ページの説明書ではなく」という教訓がある。巨大な指示ファイルはコンテキストを圧迫し、AIがタスク・コード・関連ドキュメントを見失う原因になる。重要なのは、必要な情報を簡潔に、構造化して提供すること。 Theo nghiên cứu của OpenAI, có một bài học quan trọng: "Hãy đưa Codex một tấm bản đồ, đừng đưa nó cuốn sách hướng dẫn 1.000 trang". File hướng dẫn quá lớn sẽ chiếm hết context và khiến AI mất dấu task, code và tài liệu liên quan. Quan trọng nhất là cung cấp thông tin cần thiết một cách súc tích, có cấu trúc.
docs/ structure Skills deferred loading Knowledge Graph AGENTS.md as map
3 要素が揃って初めて成立する「実験 → 検証 → 学習 → 改善」のサイクル Chu trình "Thử nghiệm → Kiểm chứng → Học hỏi → Cải tiến" chỉ vận hành khi cả 3 yếu tố đầy đủ
フィードバックループが無ければ、AIは同じミスを永遠に繰り返す。ルールファイルが無ければ、AIは過去の失敗を記憶できない。コンテキスト管理が無ければ、AIは「なぜこの改善が必要なのか」を理解できない。3 要素が揃って初めて、AIは「ツール」から「同僚」へと進化する。 Không có Feedback Loop, AI sẽ lặp lại cùng một lỗi mãi mãi. Không có Rule File, AI không thể ghi nhớ những thất bại trong quá khứ. Không có Context Management, AI không hiểu được "tại sao cần cải tiến chỗ này". Chỉ khi cả 3 yếu tố hội đủ, AI mới thực sự tiến hoá từ "công cụ" thành "đồng nghiệp".
ドメイン知識を再利用可能な単位にパッケージ化 Đóng gói tri thức thành đơn vị tái sử dụng
Claude Agent Skills は、特定領域のドメイン知識・手順・テンプレートをフォルダ単位でまとめた「スキル」のこと。エージェントは必要になった時だけ該当スキルを読み込む (deferred loading) — コンテキストを節約しながら、深い専門性を提供できる。Tinhvan Japan のプロジェクト現場知をスキル化することで、組織のノウハウが資産として蓄積される。 Claude Agent Skills là cách đóng gói tri thức chuyên ngành, quy trình và template thành từng thư mục — gọi là "skill". Agent chỉ nạp skill liên quan khi thực sự cần (deferred loading), nhờ đó vừa tiết kiệm context vừa giữ được chuyên môn sâu. Khi tri thức từ hiện trường dự án của Tinhvan Japan được đóng gói thành skill, know-how của tổ chức sẽ được tích luỹ và trở thành tài sản dùng lâu dài.
Skill の中身 — 何が入っているかBên trong một Skill
- SKILL.mdスキルの「顔」となるドキュメント。YAML frontmatter に `name` と `description` を書き、エージェントはこの description を読んで「今このスキルが必要か」を判断する。Tài liệu "mặt tiền" của skill. YAML frontmatter ghi `name` và `description` — agent đọc description để quyết định "có cần skill này lúc này không".
- 手順書領域特有の作業手順、ベストプラクティス、注意点を Markdown で記述。例:「DOCX 生成時の注意」「PowerPoint テンプレ適用手順」など。Quy trình làm việc đặc thù, best practice, lưu ý viết bằng Markdown. Ví dụ: "Lưu ý khi sinh file DOCX", "Quy trình apply template PowerPoint".
- Scriptsその領域で繰り返し使うコード、ヘルパー関数、ツール。Python/Bash/TypeScript 等を必要に応じて同梱できる。Code, helper function, tool dùng lặp trong lĩnh vực đó. Có thể đính kèm Python/Bash/TypeScript khi cần.
- Templates定型フォーマット、雛形ファイル、サンプル設定。エージェントが「ゼロから書く」のではなく「正しい雛形から始める」状態を作る。Format định sẵn, file mẫu, config sample. Agent không "viết từ zero" mà "bắt đầu từ mẫu chuẩn".
- deferred loadセッション開始時には description だけが見える状態。エージェントが「使うべき」と判断した瞬間、初めて中身全体が読み込まれる。コンテキスト窓を浪費しない設計。Lúc bắt đầu session chỉ thấy description. Khi agent quyết định "cần dùng", lúc đó mới nạp toàn bộ nội dung. Thiết kế không lãng phí context window.
典型的なディレクトリ構造Cấu trúc thư mục điển hình
└── skills/
├── docx-generation/
│ ├── SKILL.md // name + description
│ ├── procedures.md
│ ├── helper.py
│ └── templates/
├── aws-migration/
│ ├── SKILL.md
│ ├── runbooks/
│ └── tvj-cases.md // TVJ 知見
└── code-review-jp/
├── SKILL.md
└── checklist.md
各スキルは独立。新しい知識領域が増えたら、新しいスキルフォルダを追加するだけで拡張できる。 Mỗi skill độc lập. Có lĩnh vực tri thức mới — chỉ cần thêm folder skill mới là mở rộng được.
多層防御 — 単一の層に頼らない Phòng vệ đa lớp — không dựa vào một lớp duy nhất
AI エージェントは強力だが故に、機密情報の漏洩リスクも高い。.gitignore 単独では不十分 — 複数の層を同時に張り、AIが秘密情報に触れない環境を機械的に強制する。 AI agent càng mạnh thì rủi ro rò rỉ thông tin nhạy cảm càng cao. Chỉ dùng .gitignore là không đủ — cần kết hợp đồng thời nhiều lớp bảo vệ để cưỡng chế bằng cơ chế máy, ngăn AI tiếp cận được secret.
pre-commit: gitleaks scan
settings.json
Input / Output マップ Bản đồ Input / Output
各フェーズで「誰が何をするか、何が入り、何が出るか」を明示する。AIとヒトの役割境界を曖昧にしないための表。 Ở mỗi giai đoạn — ai làm gì, đầu vào là gì, đầu ra là gì — tất cả đều được làm rõ. Bảng này giúp ranh giới vai trò giữa AI và con người không bao giờ bị mơ hồ.
- Codebase
- 生ドキュメントRaw docs
- 暗黙知Tribal knowledge
/init→ パターン抽出extract patterns- CLAUDE.md ドラフト生成Generate CLAUDE.md draft
- レビュー + 承認Review + approve
- 文脈追加Add context
docs/folderCLAUDE.mdv1
- 技術スタックTech stack
- 規約Conventions
- コミュニティ Skill reposCommunity Skill repos
- スキルをカスタマイズCustomise skills
- コマンド + Hook 起草Draft commands + hooks
- スキルレビューReview skills
- コマンド検証Test commands
- Hook 承認Approve hooks
.claude/skills/.claude/commands/settings.json
- チケット URLTicket URL
- または概要hoặc tóm tắt
- MCP 経由でチケット読込Đọc ticket qua MCP
- 不明点を質問Hỏi điểm chưa rõ
- タスクファイル作成Tạo file task
- タスクファイル確認Xem lại file task
- 承認Phê duyệt
TASK-xxx.mddocs/tasks/
- 承認済タスクファイルFile task đã phê duyệt
- アプローチ提案Đề xuất approach
- ADR 整合性チェックCheck ADR consistency
- 変更ファイル一覧Liệt kê file phải sửa
- 計画承認Duyệt kế hoạch
- または方向修正hoặc đổi hướng
- 設計メモDesign notes
- 更新タスクファイルTask file cập nhật
/featureTASK-xxx
- スキル + ルール読込Load skills + rules
- TDD でテスト先行Test trước (TDD)
- 実装 + 自己レビューImplement + self-review
- 差分レビューReview diff
- 受入基準を手動テストTest AC thủ công
- ソースコードSource code
- 単体テストUnit tests
- 更新タスクログTask log cập nhật
/test [file]/e2e [scenario]
- テスト計画生成Sinh test plan
- 承認待ちChờ phê duyệt
- テスト記述 + 実行Viết + chạy test
- シナリオレビューReview scenarios
- 承認Phê duyệt
- テストファイルTest files
- カバレッジレポートBáo cáo coverage
/deploy [env]
- デプロイ前チェックリストChecklist trước deploy
- ステージングで E2EE2E trên staging
- シークレットスキャンScan secret
- リリースノートRelease notes
- 最終承認Duyệt cuối
- デプロイログDeploy log
- E2E 結果E2E results
- リリースノートRelease notes
- 随時Bất cứ lúc nào
- バグ・パターン・新ツールBug, pattern, tool mới
- 反復パターン / エラーに対する更新提案Đề xuất cập nhật cho pattern lặp / lỗi
- レビュー + 改善マージReview + merge cải tiến
CLAUDE.md更新cập nhật- 新/更新スキルSkill mới / cập nhật
守るべき 五箇条 Năm tôn chỉ cần giữ
Tinhvan Japan が現場で繰り返し検証してきた、AI 駆動開発の設計原則。これらを外すと、フレームワーク全体の効果が急速に失われる。 Năm nguyên tắc thiết kế cho AI-Driven Development mà Tinhvan Japan đã kiểm chứng nhiều lần qua thực tiễn dự án. Bỏ qua bất kỳ nguyên tắc nào, hiệu quả của toàn bộ framework sẽ suy giảm rất nhanh.
- 万能AIは存在しない — 業務文脈や規約を知らないモデルは、それらしいが誤った実装を生む。Không tồn tại AI vạn năng — một model không nắm được nghiệp vụ và quy ước sẽ chỉ tạo ra code trông có vẻ đúng nhưng thực chất sai.
- 「すべてを任せる」発想を捨て、明確な境界と役割を設定する。Cần từ bỏ tư duy "giao hết cho AI" và thiết lập ranh giới, vai trò rõ ràng cho từng thành phần.
- Business / Architect / Development / QA / Reviewer / Documentation など、領域別の専門エージェントを編成する。Tổ chức đội ngũ agent chuyên môn theo từng lĩnh vực: Business / Architect / Development / QA / Reviewer / Documentation.
- 各エージェントは独立したコンテキストウィンドウを持ち、互いに汚染しない。Mỗi agent có context window độc lập, không gây nhiễu lẫn nhau.
- 専門特化により、深い精度と高い再現性が両立する。Nhờ chuyên môn hoá, vừa đạt được độ chính xác sâu vừa giữ được tính tái lập cao.
- 巧みなプロンプトは個人のノウハウに留まり、組織資産にならない。スケールしない。Prompt hay chỉ nằm trong đầu cá nhân, không trở thành tài sản chung của tổ chức và không thể nhân rộng.
- コマンド・スキル・サブエージェントとして体系化し、チーム全員が同じ品質を再現できるようにする。Hệ thống hoá thành command, skill và sub-agent — để cả team đều có thể tái lập được cùng một mức chất lượng.
- 属人化を排除することが、AI 駆動開発を本格運用に乗せる唯一の道。Loại bỏ sự phụ thuộc cá nhân là con đường duy nhất để đưa AI-Driven Development vào vận hành ở quy mô thực.
- 仕様・コードグラフ・ADR・APIスキーマ・ナレッジグラフを整備していない状態でAIを広げると、誤りが指数的に増える。Khi chưa chuẩn bị xong spec, code graph, ADR, API schema và knowledge graph mà đã mở rộng AI — sai sót sẽ tăng theo cấp số nhân.
- 「AIに地図を渡せ、千ページの説明書ではなく」— OpenAI の教訓。"Hãy đưa AI một tấm bản đồ, đừng đưa nó cuốn sách hướng dẫn ngàn trang" — bài học từ OpenAI.
- FOUNDATION FIRST — 基盤が固まってから、エージェント体制を拡大する。FOUNDATION FIRST — nền móng vững chắc trước, rồi mới mở rộng đội ngũ agent.
- AI は提案する、人間が決める。重要な設計、トレードオフ、リスク判断は人間が握る。AI đưa ra đề xuất, con người ra quyết định. Thiết kế quan trọng, đánh đổi và đánh giá rủi ro — đều thuộc về con người.
- Human-in-the-loop を恒久的に組み込み、AIの暴走を防ぐ。Tích hợp Human-in-the-loop một cách bền vững để ngăn AI đi chệch hướng.
- ドメイン知識のエンコードは人間にしかできない仕事。Việc mã hoá tri thức nghiệp vụ là việc duy nhất chỉ con người mới làm được.
Context window を制御し、 モデルに縛られない 開発体制へ。 Kiểm soát Context Window, đạt được thể chế phát triển không phụ thuộc model.
- 手書きコードの場合の約 1/10 の期間で完了Hoàn thành trong khoảng 1/10 thời gian so với viết tay
- 3 人のエンジニアで 5 ヶ月、約 100 万行コードを生成3 kỹ sư trong 5 tháng tạo ra khoảng 1 triệu dòng code
- 1 ヶ月のスプリントが数日で完結可能にSprint dài 1 tháng có thể hoàn thành chỉ trong vài ngày
- モデル変更 +1 点、ハーネス設計 +22 点Đổi model thì được +1 điểm, còn thiết kế harness lại được +22 điểm
- 最新モデルへの依存より、環境整備の方が圧倒的に効くĐầu tư cho môi trường mang lại hiệu quả vượt trội so với chạy theo model mới nhất
- 同じモデルでも、ハーネス次第で出力品質が劇的に変わるCùng một model, nhưng harness khác nhau thì chất lượng output khác hẳn
- OpenAI 実験: 1,500 件の PR が自動生成・マージ済みThực nghiệm tại OpenAI: 1.500 PR được tự động sinh và merge
- 単一の Codex 実行が 6 時間以上自律稼働 (人間就寝中も)Một lần chạy Codex có thể tự chủ hoạt động hơn 6 tiếng (kể cả lúc con người đang ngủ)
- 従来比 約 2 倍のマージ済 PR (Business Insider 調査)Số PR được merge cao gấp khoảng 2 lần so với cách làm truyền thống (theo Business Insider)
- 属人化したプロンプトへの依存ゼロHoàn toàn không phụ thuộc vào prompt cá nhân
- ワークフローとスキルが組織資産として蓄積Workflow và skill được tích luỹ thành tài sản chung của tổ chức
- チーム全員が同じ品質と一貫性を再現可能Cả team đều có thể tái lập cùng một mức chất lượng và sự nhất quán