AI駆動 開発の 設計思想 Tư duy thiết kế phát triển AIDesign philosophy for AI-driven development
「何でも知っている 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.Rather than building a "know-it-all AI", this framework orchestrates a team of specialized agents and controls context within each domain — the answer Tinhvan Japan drew from real-world implementation.
全体の 流れ と関係性 Dòng chảy và mối liên hệ tổng thểThe overall flow and relationships
知識基盤(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ể.First, build the Knowledge Foundation (Layer 1). The multi-agent system (Layer 2) then runs on that material. As they work, agents write what they learn back to the Knowledge Foundation, while humans hold the final decisions and overall direction.
人間が 必ず 関与する Con người bắt buộc phải tham giaHumans must be involved
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.However far AI's autonomy expands, the core principle stands: important decisions, approvals, and final responsibility belong to humans. AI handles proposals, implementation, and verification — but release go/no-go, design trade-offs, business risk acceptance, and compliance judgments are all decided by humans.
明確で構造化された Input Input rõ ràng và có cấu trúcClear, structured Input
曖昧なプロンプトは曖昧な結果を生む。要件、文脈、制約は明示的かつ整然と提供する必要がある。 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.Vague prompts produce vague results. Requirements, context, and constraints must be provided explicitly and in an orderly way.
判断と決定権 Phán đoán & Quyền quyết địnhJudgment & Decision authority
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ữ.AI proposes, humans decide. Key design choices, trade-offs, and risk judgments stay with humans.
フィードバック & 継続レビュー Phản hồi & Review liên tụcFeedback & Continuous review
スキルとワークフローは、人間が 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.Skills and workflows improve only when humans actively review AI output and feed corrections back into the system.
クロスファンクショナルな連携 Phối hợp đa chức năngCross-functional collaboration
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.AI-DLC spans Dev / QA / BA / Ops. Humans coordinate and connect across departments.
専用ツールで 知識基盤 を築く Dựng nền tri thức bằng công cụ chuyên biệtBuild the Knowledge Foundation with dedicated tools
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.Before handing anything to AI, structure it in a form humans can understand. From specs, code, and architecture to the reasoning behind decisions — each in the format that suits it.
仕様 & 業務知識Spec & BusinessSpec & Business
各種ドキュメントをAIが扱える形式へ正規化する。Chuẩn hoá tài liệu đa dạng về dạng AI có thể đọc.Normalize diverse documents into a form AI can read.
コードグラフGraph ContextGraph Context
関数・モジュール・呼出関係をグラフ化し、文脈を圧縮する。Đồ thị hoá hàm, module, quan hệ gọi — nén context.Graph functions, modules, and call relationships — compressing context.
アーキテクチャ図Architecture & FlowArchitecture & Flow
システム構造をコードで管理し、版を追えるようにする。Quản lý cấu trúc hệ thống bằng code, theo được phiên bản.Manage system structure as code, with version tracking.
規約 & ルールファイルCoding Standards & RulesCoding 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.Document the rules AI must follow in AGENTS.md / CLAUDE.md — leaving no ambiguous tacit knowledge.
意思決定の記録Historical DecisionsHistorical 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.Record "why we decided this way" as ADRs. Technology-choice rationale and business constraints — in a form AI can reference.
API & スキーマAPI & SchemaAPI & 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.Feed OpenAPI, GraphQL, and DB schemas to AI as the source of truth. Interface definitions are the most trustworthy context.
依存関係 & 影響分析Dependency & ImpactDependency & 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.Visualize where a change ripples across the knowledge graph — ensuring safe edits.
Knowledge Foundation: ツール Knowledge Foundation: Bộ công cụKnowledge Foundation: Toolkit
知識抽出を高速かつ確実にする推奨ツール Bộ công cụ giúp trích xuất tri thức nhanh và đáng tin cậyRecommended tools for fast, reliable knowledge extraction.
ブラウザ上でインタラクティブなグラフを構築。コード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.Build interactive graphs right in the browser. Includes a Graph RAG agent for code Q&A.
ニッチな JS lib、独自 DSL、COBOL、Delphi は tree-sitter パーサを手動で書く必要あり。JS lib hiếm, DSL custom, COBOL, Delphi cần tree-sitter parser thủ công.Niche JS libs, custom DSLs, COBOL, and Delphi need hand-written tree-sitter parsers.
任意のコードベースをインタラクティブな知識グラフに変換。マルチプラットフォーム対応。 Biến mọi codebase thành knowledge graph tương tác. Hỗ trợ đa nền tảng.Turn any codebase into an interactive knowledge graph. Multi-platform support.
/understand-anything コマンドで関係性と呼出チェーンを検索。 Tìm quan hệ và call chain qua lệnh /understand-anything.Search relationships and call chains with the /understand-anything command.
↗ 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.Microsoft's PDF/DOCX/PPTX → Markdown converter. Essential for building AI context.
日本語エンコーディング (Shift-JIS)、ふりがな除去、文書構造のアダプタが必要。Cần adapter cho encoding Nhật (Shift-JIS), bỏ furigana, cấu trúc doc.Needs adapters for Japanese encoding (Shift-JIS), furigana removal, and document structure.
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.The standard file popularized by Mitchell Hashimoto through the Ghostty project. It captures "where everything lives" in about 100 lines, keeping detailed knowledge under docs/. Context is a scarce resource. OpenAI adopted this approach too, in its million-line Codex trial.
- プロジェクト構造のマップ
- ビルド・テストコマンド
- コーディング規約の要点
- 過去の失敗パターン (アンチパターン)
- 詳細は docs/ への参照ポインタ
- Bản đồ cấu trúc dự án
- Map of the project structure
- Các lệnh build & test
- Build & test commands
- Các điểm chính trong quy ước code
- Key points of the code conventions
- Anti-pattern — những lỗi đã từng mắc
- Anti-patterns — mistakes made before
- Con trỏ tới docs/ để xem chi tiết
- Pointers to docs/ for the details
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/.The file Claude Code always reads at session start. Written table-of-contents style, like AGENTS.md. Detailed procedures are deferred-loaded via SKILL.md files under .claude/skills/.
- 常に守るべき原則(短く)
- 主要ファイル・ディレクトリへのマップ
- 使用すべきコマンド・スクリプト
- 禁止事項と境界条件
- .claude/skills/ への参照
- Nguyên tắc cần luôn tuân thủ (ngắn gọn)
- Principles to always follow (concise)
- Bản đồ các file & thư mục chính
- Map of the key files & folders
- Các lệnh và script nên dùng
- Recommended commands and scripts
- Điều cấm và ràng buộc biên
- Prohibitions and boundary constraints
- Tham chiếu tới .claude/skills/
- References to .claude/skills/
プロジェクト構造Cấu trúc dự ánProject structure
全フォルダツリー — 各ファイルの役割を解説。クリックで展開/折りたたみ。Toàn bộ cây thư mục — vai trò từng file. Click để mở/đóng từng cấp.The full folder tree — the role of every file. Click to expand/collapse each level.
▶
project-root/
▶
.claude/
▶
docs/
▶
requirements/Always
PRDファイル — 1機能/1エピックにつき1ファイルFile PRD — mỗi feature/epic một filePRD files — one file per feature/epic
▶
architecture/
▶
decisions/Always
ADR — 承認後は不変ADR — bất biến sau khi duyệtADR — immutable after approval
▶
api-contracts/On-demand
ドメイン毎のAPIスキーマAPI schema theo từng domainAPI schema per domain
▶
tasks/
▶
active/Manual
現スプリント — AIセッションログSprint hiện tại — log session AICurrent sprint — AI session logs
▶
done/Manual
完了後に移動 — 履歴参照用Move sau khi merge — lưu lịch sửMove after merge — for history reference
▶
context/On-demand
AI 特化の長期記憶Tri thức dài hạn cho AILong-term memory for AI
▶
templates/Manual
新規ファイル用コピペ雛形Mẫu copy-paste cho file mớiCopy-paste template for new files
▶
src/
専門特化 したマルチエージェント Multi-agent chuyên môn hoáMulti-agent specialization
各エージェントは担当領域に特化したスキルとコマンドで動く。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.Each agent runs on a set of Skills and commands specialized to its domain. The knowledge Tinhvan Japan has accumulated across projects forms the core of these skill sets.
業務エージェントBusiness AgentBusiness 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.Reads and interprets requirements and business logic. Frames issues in the customer's language and bridges them to the technical side.
アーキテクトエージェントArchitect AgentArchitect 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.Owns system structure and technology selection. References ADRs and existing architecture to deliver consistent designs.
開発エージェント群Development AgentsDevelopment 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.A group of specialized agents that own implementation. Split across front-end, back-end, infra, and more — each agent uses its own skills to handle its part.
品質・セキュリティQA & Security AgentsQA & 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.Handles it all: generating test cases, scanning for vulnerabilities, and automatically applying security rules.
レビュアーエージェントReviewer AgentReviewer 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.Inspects other agents' output against coding conventions and design intent. The first line of defense before human review.
ドキュメントエージェントDocumentation AgentDocumentation 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.Keeps spec changes, ADRs, and API schemas in sync with the implementation — ensuring the Knowledge Foundation never goes stale.
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."Harness" refers to the tack and gear strapped onto a horse. A powerful horse (the LLM) will run wild if left alone — the harness is what channels it in a useful direction. Coined by Mitchell Hashimoto (co-founder of Terraform) and formally proposed by OpenAI in February 2026, it is a new engineering discipline for the AI era.
ルールファイル × フィードバックループ × コンテキスト管理 Rule File × Feedback Loop × Context ManagementRule 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á.The foundation of the Harness is built from three elements. According to Martin Fowler's analysis, putting all three in place dramatically improves the output quality of AI agents.
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.A document that codifies the coding conventions, naming rules, and prohibitions an AI agent must follow. Place .claude/rules.md or CONTRIBUTING.md at the project root and let the AI read it — the result is consistent code generation.
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.The AGENTS.md that Mitchell Hashimoto publishes in the Ghostty project is now widely referenced as a textbook example of harness design. It contains the project structure, build/test commands, coding conventions, and a list of anti-patterns the AI has repeatedly hit — functioning as a "study notebook" that keeps the AI from making the same mistake twice.
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.A mechanism that tests and verifies AI output, detects failures, and forces the AI to retry. It integrates a CI/CD pipeline, automated tests, and static analysis to automatically check whether the code the AI generates meets quality standards.
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.In OpenAI's experiment, roughly 1,500 pull requests were automatically generated and merged — behind them, a robust feedback loop was at work. When a test fails, the AI automatically reads the error message and fixes the code. When static analysis flags a convention violation, the AI consults the rule file and regenerates the code. Running this cycle at high speed produces high-quality code with no human intervention.
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".Provide the right information so AI can judge correctly. Organize project structure, dependencies, past decisions and architecture documents — so AI can understand "why this piece of code is here".
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.According to OpenAI research, there is a key lesson: "Give Codex a map, not a 1,000-page manual". An oversized instruction file eats up the context and causes AI to lose track of the task, the code and related documents. What matters most is providing the needed information concisely and in a structured way.
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 đủThe "Experiment → Verify → Learn → Improve" cycle only works when all 3 elements are in place
フィードバックループが無ければ、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".Without a Feedback Loop, AI repeats the same mistake forever. Without a Rule File, AI cannot remember past failures. Without Context Management, AI cannot understand "why this needs improving". Only when all 3 elements come together does AI truly evolve from a "tool" into a "colleague".
ドメイン知識を再利用可能な単位にパッケージ化 Đóng gói tri thức thành đơn vị tái sử dụngPackage knowledge into reusable units
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.Claude Agent Skills are a way to package domain knowledge, procedures and templates into folders — called "skills". An agent loads only the relevant skill when it actually needs it (deferred loading), saving context while retaining deep expertise. When field knowledge from Tinhvan Japan projects is packaged into skills, the organization's know-how accumulates as a lasting asset.
Skill の中身 — 何が入っているかBên trong một SkillInside a 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".The "front door" document of a skill. The YAML frontmatter holds `name` and `description` — the agent reads the description to decide "whether this skill is needed right now".
- 手順書領域特有の作業手順、ベストプラクティス、注意点を 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".Domain-specific workflows, best practices and notes written in Markdown. For example: "Notes when generating DOCX files", "Procedure to apply a PowerPoint template".
- 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.Code, helper functions and tools reused within that domain. Python/Bash/TypeScript can be bundled as needed.
- 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".Preset formats, template files, sample configs. The agent doesn't "write from zero" but "starts from a proper template".
- 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.At the start of a session, only the description is visible. The moment the agent decides "this is needed", the full content is loaded. A design that doesn't waste the context window.
典型的なディレクトリ構造Cấu trúc thư mục điển hìnhTypical directory structure
└── 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.Each skill is independent. When a new knowledge domain appears — just add a new skill folder to extend it.
多層防御 — 単一の層に頼らない Phòng vệ đa lớp — không dựa vào một lớp duy nhấtMulti-layer defense — never rely on a single layer
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.The more powerful the AI agent, the higher the risk of leaking sensitive information. .gitignore alone is not enough — you need to combine multiple protective layers at once to mechanically enforce that AI cannot reach secrets.
pre-commit: gitleaks scan
settings.json
Input / Output マップ Bản đồ Input / OutputInput / Output map
各フェーズで「誰が何をするか、何が入り、何が出るか」を明示する。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ồ.At each phase — who does what, what goes in, what comes out — all made explicit. This table keeps the boundary between AI and human roles from ever becoming blurred.
- Codebase
- 生ドキュメントRaw docsRaw docs
- 暗黙知Tribal knowledgeTribal knowledge
/init→ パターン抽出extract patternsextract patterns- CLAUDE.md ドラフト生成Generate CLAUDE.md draftGenerate CLAUDE.md draft
- レビュー + 承認Review + approveReview + approve
- 文脈追加Add contextAdd context
docs/folderCLAUDE.mdv1
- 技術スタックTech stackTech stack
- 規約ConventionsConventions
- コミュニティ Skill reposCommunity Skill reposCommunity Skill repos
- スキルをカスタマイズCustomise skillsCustomise skills
- コマンド + Hook 起草Draft commands + hooksDraft commands + hooks
- スキルレビューReview skillsReview skills
- コマンド検証Test commandsTest commands
- Hook 承認Approve hooksApprove hooks
.claude/skills/.claude/commands/settings.json
- チケット URLTicket URLTicket URL
- または概要hoặc tóm tắtor summary
- MCP 経由でチケット読込Đọc ticket qua MCPRead ticket via MCP
- 不明点を質問Hỏi điểm chưa rõAsk about unclear points
- タスクファイル作成Tạo file taskCreate task file
- タスクファイル確認Xem lại file taskReview task file
- 承認Phê duyệtApprove
TASK-xxx.mddocs/tasks/
- 承認済タスクファイルFile task đã phê duyệtApproved task file
- アプローチ提案Đề xuất approachPropose approach
- ADR 整合性チェックCheck ADR consistencyCheck ADR consistency
- 変更ファイル一覧Liệt kê file phải sửaList files to change
- 計画承認Duyệt kế hoạchApprove plan
- または方向修正hoặc đổi hướngor course correction
- 設計メモDesign notesDesign notes
- 更新タスクファイルTask file cập nhậtUpdated task file
/featureTASK-xxx
- スキル + ルール読込Load skills + rulesLoad skills + rules
- TDD でテスト先行Test trước (TDD)Tests first (TDD)
- 実装 + 自己レビューImplement + self-reviewImplement + self-review
- 差分レビューReview diffReview diff
- 受入基準を手動テストTest AC thủ côngManually test AC
- ソースコードSource codeSource code
- 単体テストUnit testsUnit tests
- 更新タスクログTask log cập nhậtUpdated task log
/test [file]/e2e [scenario]
- テスト計画生成Sinh test planGenerate test plan
- 承認待ちChờ phê duyệtAwait approval
- テスト記述 + 実行Viết + chạy testWrite + run tests
- シナリオレビューReview scenariosReview scenarios
- 承認Phê duyệtApprove
- テストファイルTest filesTest files
- カバレッジレポートBáo cáo coverageCoverage report
/deploy [env]
- デプロイ前チェックリストChecklist trước deployPre-deploy checklist
- ステージングで E2EE2E trên stagingE2E on staging
- シークレットスキャンScan secretSecret scan
- リリースノートRelease notesRelease notes
- 最終承認Duyệt cuốiFinal approval
- デプロイログDeploy logDeploy log
- E2E 結果E2E resultsE2E results
- リリースノートRelease notesRelease notes
- 随時Bất cứ lúc nàoAnytime
- バグ・パターン・新ツールBug, pattern, tool mớiBugs, patterns, new tools
- 反復パターン / エラーに対する更新提案Đề xuất cập nhật cho pattern lặp / lỗiUpdate proposals for recurring patterns / errors
- レビュー + 改善マージReview + merge cải tiếnReview + merge improvements
CLAUDE.md更新cập nhậtupdate- 新/更新スキルSkill mới / cập nhậtNew / updated Skill
守るべき 五箇条 Năm tôn chỉ cần giữFive tenets to uphold
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.Five design principles for AI-driven development that Tinhvan Japan has validated repeatedly in the field. Drop any one of them, and the effectiveness of the entire framework degrades rapidly.
- 万能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.There is no all-purpose AI — a model that doesn't grasp your business context and conventions will only produce code that looks right but is actually wrong.
- 「すべてを任せる」発想を捨て、明確な境界と役割を設定する。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.Abandon the "delegate everything to AI" mindset and set clear boundaries and roles for each component.
- 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.Orchestrate a team of specialized agents by domain: Business / Architect / Development / QA / Reviewer / Documentation.
- 各エージェントは独立したコンテキストウィンドウを持ち、互いに汚染しない。Mỗi agent có context window độc lập, không gây nhiễu lẫn nhau.Each agent has an independent context window, so they don't contaminate one another.
- 専門特化により、深い精度と高い再現性が両立する。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.Specialization delivers both deep accuracy and high reproducibility.
- 巧みなプロンプトは個人のノウハウに留まり、組織資産にならない。スケールしない。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.A clever prompt stays in one person's head — it never becomes a shared organizational asset, and it doesn't scale.
- コマンド・スキル・サブエージェントとして体系化し、チーム全員が同じ品質を再現できるようにする。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.Systematize them into commands, Skills, and sub-agents so the whole team can reproduce the same quality.
- 属人化を排除することが、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.Eliminating individual dependency is the only way to bring AI-driven development into real-scale operation.
- 仕様・コードグラフ・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.Scaling AI before your specs, code graph, ADRs, API schema, and knowledge graph are in place makes errors grow exponentially.
- 「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."Give AI a map, not a thousand-page manual" — a lesson from 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.FOUNDATION FIRST — solidify the foundation, then scale up the agent team.
- 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.AI proposes, humans decide. Critical design, trade-offs, and risk judgment all stay with humans.
- 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.Embed Human-in-the-Loop permanently to keep AI from running off course.
- ドメイン知識のエンコードは人間にしかできない仕事。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.Encoding domain knowledge is work that only humans can do.
Context window を制御し、 モデルに縛られない 開発体制へ。 Kiểm soát Context Window, đạt được thể chế phát triển không phụ thuộc model.Control the context window, for a development structure that is model-agnostic.
- 手書きコードの場合の約 1/10 の期間で完了Hoàn thành trong khoảng 1/10 thời gian so với viết tayCompleted in about 1/10 the time of hand-written code
- 3 人のエンジニアで 5 ヶ月、約 100 万行コードを生成3 kỹ sư trong 5 tháng tạo ra khoảng 1 triệu dòng code3 engineers generated ~1 million lines of code in 5 months
- 1 ヶ月のスプリントが数日で完結可能にSprint dài 1 tháng có thể hoàn thành chỉ trong vài ngàyA one-month sprint can be finished in just a few days
- モデル変更 +1 点、ハーネス設計 +22 点Đổi model thì được +1 điểm, còn thiết kế harness lại được +22 điểmChanging the model: +1 point; designing the Harness: +22 points
- 最新モデルへの依存より、環境整備の方が圧倒的に効くĐầ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ấtInvesting in the environment vastly outperforms chasing the latest model
- 同じモデルでも、ハーネス次第で出力品質が劇的に変わるCùng một model, nhưng harness khác nhau thì chất lượng output khác hẳnWith the same model, output quality changes dramatically depending on the Harness
- OpenAI 実験: 1,500 件の PR が自動生成・マージ済みThực nghiệm tại OpenAI: 1.500 PR được tự động sinh và mergeOpenAI experiment: 1,500 PRs auto-generated and merged
- 単一の 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ủ)A single Codex run can operate autonomously for over 6 hours (even while humans sleep)
- 従来比 約 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)About 2x the merged PRs vs traditional methods (Business Insider study)
- 属人化したプロンプトへの依存ゼロHoàn toàn không phụ thuộc vào prompt cá nhânZero dependency on individual prompts
- ワークフローとスキルが組織資産として蓄積Workflow và skill được tích luỹ thành tài sản chung của tổ chứcWorkflows and Skills accumulate as shared organizational assets
- チーム全員が同じ品質と一貫性を再現可能Cả team đều có thể tái lập cùng một mức chất lượng và sự nhất quánThe whole team can reproduce the same quality and consistency