Hướng dẫn Claude Opus 4.5: Xây dựng Agent GitHub Wiki

Nhiều kho GitHub hiện đại thiếu tài liệu rõ ràng, có cấu trúc, đặc biệt là wiki.

Tạo các trang này thủ công có thể tốn hàng giờ đọc mã, hiểu kiến trúc và sắp xếp nội dung.

Một Agent AI cho GitHub Wiki có thể giải quyết vấn đề này.

Trong hướng dẫn này, tôi sẽ chỉ cho bạn cách xây dựng một GitHub Wiki AI Agent tự động hoàn toàn, một công cụ dòng lệnh sử dụng Claude Opus 4.5 và Claude Agent SDK để tạo trọn bộ wiki cho kho GitHub chỉ với một chỉ thị. 

Thay vì viết tài liệu thủ công, công cụ này sẽ phân tích codebase, hiểu cấu trúc của nó và tạo nội dung wiki nhiều trang, sạch sẽ, được tự động commit và xuất bản lên kho của bạn. 

Mọi thứ chạy qua ứng dụng CLI tương tác được thiết kế để mang lại cảm giác nhanh, thông minh và thân thiện với nhà phát triển.

Trong hướng dẫn này, chúng ta sẽ theo quy trình ba bước đơn giản để thiết lập môi trường, xây dựng GitHub Wiki AI Agent và kiểm thử trên các kho thực tế:

1. Thiết lập môi trường: cài đặt phụ thuộc, cài đặt và xác thực Claude Code, cấu hình token GitHub và bật tính năng Wiki.
2. Xây dựng ứng dụng: tạo công cụ CLI, cấu hình Claude Agent, tích hợp công cụ MCP GitHub, thêm theo dõi chi phí và triển khai logic tạo wiki (Home, Getting Started, Architecture & Tools).
3. Kiểm thử agent: chạy trên các kho thực (ECom-Intel và Issue-Analyzer) để xác minh thao tác clone, phân tích, tạo wiki và tự động đẩy.

Nếu bạn mới làm quen với AI agent và muốn tìm hiểu thêm, tôi khuyến nghị xem lộ trình kỹ năng AI Agent Fundamentals. Bạn cũng nên đọc hướng dẫn về Claude Cowork và bài giới thiệu về Claude Opus 4.6.

Thiết lập môi trường cho Hướng dẫn GitHub Wiki với Claude Opus 4.5

Trước khi xây dựng GitHub Wiki Agent với Opus 4.5, hãy đảm bảo môi trường của bạn được cấu hình đúng. Phần này sẽ hướng dẫn bạn mọi điều kiện tiên quyết và các bước thiết lập.

1. Điều kiện tiên quyết để chạy Claude Opus 4.5 Wiki Agent

• Python 3.11 trở lên (yêu cầu bởi Python Claude Agent SDK).
• Node.js và npm (cần để cài đặt Claude Code), là xương sống của ứng dụng và cung cấp agent, công cụ, cũng như tích hợp với máy chủ MCP.

2. Cài đặt và xác thực Claude Code

Mở terminal (Command Prompt, PowerShell hoặc Terminal trên macOS) và chạy lệnh sau để cài đặt Claude Code CLI:

npm install -g @anthropic-ai/claude-code

Gõ claude trong terminal để khởi động Claude Code. Sau đó, trong phần chat của Claude, gõ /login để xác thực và truy cập mô hình Opus 4.5 cùng các công cụ như bên dưới.

Bạn có thể tìm hiểu thêm về Claude Code trong hướng dẫn thực hành của chúng tôi. 

3. Tạo GitHub Personal Access Token chi tiết

Để tạo GitHub Personal Access Token chi tiết, truy cập GitHub và điều hướng đến: 

Settings → Developer Settings → Personal Access Tokens → Fine-grained tokens. 

Tạo token mới và chọn kho bạn sẽ dùng trong phần Repository. Sau đó cấu hình Permissions. Vì lý do bảo mật, khuyến nghị đặt thời hạn hiệu lực ngắn cho token.

Sau đó, đặt Personal Access Token làm biến môi trường:

export GITHUB_PAT="your-github-personal-access-token"

4. Khởi tạo GitHub Wiki của bạn

Hiện tại GitHub không hỗ trợ tạo Wiki cục bộ trước.

Vì vậy, bạn phải khởi tạo wiki thủ công bằng cách:

1. Mở kho của bạn trên GitHub
2. Nhấp vào tab Wiki
3. Nhấp “Create the first page”
4. Lưu trang (tiêu đề nào cũng được)

5. Cài đặt Claude Agent SDK

Chúng ta sẽ cài đặt framework Agentic của Claude, framework này xử lý mọi thứ từ việc dùng MCP đến gọi công cụ, tạo tệp và đẩy thay đổi lên remote.

pip install claude-agent-sdk

Xây dựng Auto Wiki Agent với Claude Opus 4.5

Bây giờ chúng ta sẽ tạo một ứng dụng CLI Python tên là gh_wiki_cli.py. Tệp này sẽ bao gồm cấu hình, agent, công cụ, client MCP, system prompt, chính ứng dụng CLI và các hàm trợ giúp. 

Các thành phần này sẽ đảm bảo người dùng có thể cung cấp liên kết tới kho và agent biết cách xử lý đúng để xuất bản GitHub wiki.

1. Import

Phần này nhập các mô-đun stdlib của Python, các công cụ typing và Claude Agent SDK.

• asyncio cho I/O bất đồng bộ (chat + streaming).
• os, sys cho biến môi trường và thoát chương trình.
• dataclass để theo dõi thống kê.
• Import Claude Agent SDK để giao tiếp với agent + công cụ MCP.

import asyncio
import os
import sys
from dataclasses import dataclass
from typing import Dict

# --- SDK Imports ---
from claude_agent_sdk import (
    AssistantMessage,
    ClaudeAgentOptions,
    ClaudeSDKClient,
    McpSdkServerConfig,
    ResultMessage,
    TextBlock,
    ToolResultBlock,
    ToolUseBlock,
)

2. System prompt

Đây là “bộ não” của agent. Chúng ta sẽ hướng dẫn mô hình Opus 4.5 về cách nó nên hành xử và cách sử dụng công cụ.

SYSTEM_PROMPT = """
        You are an expert Technical Writer and GitHub Wiki specialist.

        TOOLS
        - Read, Write, Glob, Grep:
        - Use these to inspect files and folders in the project directory (e.g. /tmp/Issue-Analyzer) and in wiki_clone/.
        - Use them to list files, read contents, and search for patterns.
        - Write:
        - Use this ONLY to write or update three wiki pages inside wiki_clone/:
            - wiki_clone/Home.md
            - wiki_clone/Getting-Started.md
            - wiki_clone/Architecture-and-Tools.md
        - Bash:
        - Bash is ONLY allowed for git commands, never for inspection or editing.
        - Allowed commands (with cd wiki_clone/ when needed):
            - git clone <repo>.wiki.git wiki_clone  (if wiki_clone does not already exist)
            - git status
            - git add .
            - git commit -m "Update wiki"
            - git push
        - Do NOT use Bash for ls, cat, grep, find, python, or any other way of reading/writing files.

        WORKFLOW
        1. When the user gives a GitHub repo URL:
        - Use Bash to clone the wiki if wiki_clone/ does not already exist:
            git clone <repo>.wiki.git wiki_clone
        2. Use Read/Glob/Grep (and any GitHub MCP tools) to explore the project:
        - Read important files in the project folder (e.g. README, docs/, src/).
        - Use that information to generate documentation.
        3. Use Write to create or update ONLY:
        - wiki_clone/Home.md
        - wiki_clone/Getting-Started.md
        - wiki_clone/Architecture-and-Tools.md
        4. When the wiki pages are ready:
        - Use Bash from wiki_clone/ to:
            git add .
            git commit -m "Update wiki"
            git push

        RULES
        - You may READ from the whole project directory and wiki_clone/.
        - You may WRITE only to the three wiki pages inside wiki_clone/.
        - Never use Bash to inspect or edit files; only use it for git commands.
        - Keep documentation clear, concise, and in GitHub Wiki style.
        """

3. Xử lý màu sắc cho CLI

Điều này giúp đầu ra CLI trông bắt mắt hơn, nhưng vẫn hoạt động nếu không cài colorama.

• Cố gắng dùng colorama để có văn bản có màu.
• Nếu không có thì rơi về MockColors để script vẫn chạy (không màu, không lỗi).

try:
    from colorama import Fore, Style, init

    init()
except ImportError:

    class MockColors:
        def __getattr__(self, name):
            return ""

    Fore = Style = MockColors()

4. Theo dõi thống kê phiên

Một dataclass nhỏ để theo dõi chi phí, số lượt và thời lượng.

• total_cost: tổng chi phí $ từ Claude SDK.
• total_turns: số lượt truy vấn bạn đã gửi.
• duration_ms: thời lượng tích lũy theo mili giây.

@dataclass
class SessionStats:
    total_cost: float = 0.0
    total_turns: int = 0
    duration_ms: int = 0

5. Tạo tùy chọn cho agent

Tiếp theo, chúng ta sẽ tạo đối tượng ClaudeAgentOptions và kết nối tới các máy chủ MCP. Hàm dưới đây xác thực các biến môi trường bắt buộc, cấu hình máy chủ MCP GitHub nếu có, và giới hạn các công cụ mà agent có thể dùng.

Chúng tôi cố ý giới hạn allowed_tools để Opus 4.5 có thể: dùng Bash cho thao tác Git, gọi máy chủ MCP GitHub để kiểm tra nội dung kho, và dùng Read/Write (cùng Glob và Grep) để làm việc với và kiểm tra các tệp Markdown cục bộ.

def create_agent_options() -> ClaudeAgentOptions:
    """Validates env vars and configures the agent options."""
    anthropic_key = os.getenv("ANTHROPIC_API_KEY")
    github_pat = os.getenv("GITHUB_PAT")

    if not anthropic_key:
        print(
            f"{Fore.RED}Error: ANTHROPIC_API_KEY environment variable is required.{Style.RESET_ALL}"
        )
        sys.exit(1)

    # Configure MCP servers
    mcp_servers: Dict[str, McpSdkServerConfig] = {}
    if github_pat:
        mcp_servers["github"] = {
            "type": "http",
            "url": "https://api.githubcopilot.com/mcp/",
            "headers": {"Authorization": f"Bearer {github_pat}"},
        }

    return ClaudeAgentOptions(
        model="claude-opus-4-5",
        system_prompt=SYSTEM_PROMPT,
        mcp_servers=mcp_servers,
        permission_mode="bypassPermissions",
        allowed_tools=[
            "Read",
            "Write",
            "Glob",
            "Grep",
            "Bash",
            "mcp__github__*",
        ],
    )

6. Xử lý phản hồi dạng streaming

Hàm này lắng nghe luồng và in văn bản, việc sử dụng công cụ và đầu ra công cụ.

• Dùng client.receive_response() như một luồng async.
• In văn bản của trợ lý ngay khi nhận được.
• Khi một công cụ được gọi → in [Tool Use: ...].
• Khi công cụ trả về đầu ra → rút gọn và in xem trước một dòng ngắn.
• Khi nhận ResultMessage → cập nhật SessionStats với chi phí + thời lượng.

async def process_response_stream(client: ClaudeSDKClient, stats: SessionStats):
    """Handles the stream of messages from the agent."""
    async for message in client.receive_response():
        # 1. Handle Assistant Content (Text & Tool Requests)
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text, end="", flush=True)
                elif isinstance(block, ToolUseBlock):
                    print(f"\n{Fore.CYAN}[Tool Use: {block.name}]{Style.RESET_ALL}")

        # 2. Handle Tool Results (Outputs)
        if hasattr(message, "content") and isinstance(message.content, list):
            for block in message.content:
                if isinstance(block, ToolResultBlock):
                    # Truncate output for cleaner CLI
                    raw_output = str(block.content)
                    clean_output = raw_output.replace("\n", " ")
                    short_output = (
                        clean_output[:200] + "..."
                        if len(clean_output) > 200
                        else clean_output
                    )
                    print(
                        f"{Fore.YELLOW}  -> [Output]: {short_output}{Style.RESET_ALL}"
                    )

        # 3. Handle Result Metrics (Cost & Usage)
        if isinstance(message, ResultMessage):
            if message.total_cost_usd:
                stats.total_cost += message.total_cost_usd
            if message.duration_ms:
                stats.duration_ms += message.duration_ms

7. In bản tóm tắt cuối phiên

Thống kê cuối phiên gọn gàng cho ứng dụng CLI, hiển thị số lượt, thời lượng và chi phí bằng đô la.

• Chuyển duration_ms sang giây.
• Hiển thị tổng chi phí định dạng 4 chữ số thập phân.

def print_summary(stats: SessionStats):
    """Prints the final session statistics."""
    print(f"\n\n{Fore.GREEN}=== Session Summary ==={Style.RESET_ALL}")
    print(f"Total Turns:   {stats.total_turns}")
    print(f"Duration:      {stats.duration_ms / 1000:.2f}s")
    print(f"Total Cost:    ${stats.total_cost:.4f}")
    print(f"{Fore.GREEN}======================={Style.RESET_ALL}")

8. Hàm async chính

Đây là luồng điều khiển cốt lõi của ứng dụng: xử lý thiết lập, kết nối dịch vụ, đọc đầu vào người dùng và gửi truy vấn. Hàm gọi create_agent_options() và khởi tạo thống kê. Nó in banner giới thiệu và cho biết máy chủ MCP nào được bật. Nó cũng tạo ClaudeSDKClient bằng ngữ cảnh bất đồng bộ.

Ứng dụng chạy một REPL đơn giản (Read-Eval-Print Loop):

1. Gõ 'exit' hoặc 'quit' để thoát ứng dụng.
2. Mỗi truy vấn hợp lệ sẽ tăng stats.total_turns thêm 1.
3. await client.query(user_input) gửi thông điệp của người dùng.
4. await process_response_stream(...) in kết quả dạng stream.
5. Mọi ngoại lệ sẽ bị bắt và hiển thị thông báo lỗi màu đỏ.
6. Cuối cùng, hàm luôn gọi print_summary(stats).

async def main():
    options = create_agent_options()
    stats = SessionStats()

    # Welcome message
    print(f"{Fore.GREEN}=== GitHub Wiki AI Agent (Auto-Mode) ==={Style.RESET_ALL}")
    print(
        f"MCP Servers: {', '.join(options.mcp_servers.keys()) if options.mcp_servers else 'None'}"
    )
    print("Ask me to help with a GitHub wiki by mentioning the repository URL!")
    print("Type 'exit' to quit.\n")

    async with ClaudeSDKClient(options=options) as client:
        try:
            await client.connect()

            while True:
                try:
                    user_input = input(f"\n{Fore.BLUE}>> {Style.RESET_ALL}").strip()
                except EOFError:
                    break

                if not user_input:
                    continue

                if user_input.lower() in ["exit", "quit"]:
                    break

                stats.total_turns += 1

                # Send query
                await client.query(user_input)
                print()  # Spacer

                # Process response stream using helper function
                await process_response_stream(client, stats)

        except Exception as e:
            print(f"\n{Fore.RED}Session Error: {e}{Style.RESET_ALL}")
        finally:
            print_summary(stats)

9. Điểm vào của script

Cuối cùng, chúng ta định nghĩa điểm vào của script để CLI chạy khi tệp được thực thi trực tiếp. Khối dưới đây khởi động vòng lặp async chính và xử lý việc tắt an toàn:

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        print("\nSession interrupted.")
        sys.exit(0)

Kiểm thử Auto Wiki Agent

Khi mọi thứ đã được cài đặt, hãy khởi động ứng dụng chat CLI và đảm bảo ứng dụng Claude Code CLI hoạt động:

python gh_wiki_cli.py

Bây giờ bạn có thể tương tác với agent như một giao diện chat. Hỏi các câu chung hoặc yêu cầu trực tiếp tạo wiki cho kho của bạn:

create the github wiki for https://github.com/kingabzpro/ECom-Intel

Nếu người dùng yêu cầu tạo wiki, agent sẽ tự động thực hiện:

1. Clone wiki: Tạo hoặc tái sử dụng thư mục wiki_clone/ và kéo nội dung wiki mới nhất.
2. Kiểm tra kho: Đọc các tệp chính từ kho GitHub bằng công cụ MCP. 
3. Tạo trang: Tự động phác thảo và viết các trang như:
• Home.md
• Getting-Started.md
• Architecture-and-Tools.md
4. Commit và đẩy: Agent đưa các trang mới vào vùng chờ, commit và đẩy cập nhật lên: <your-repo>.wiki.git
5. Ví dụ đầu ra thành công: Khi hoàn tất, bạn sẽ thấy thông báo xác nhận rõ ràng. Và wiki sẽ hiển thị tại: https://github.com/kingabzpro/ECom-Intel/wiki

Tôi thực sự ấn tượng với cách agent có thể thu thập hình ảnh demo, biểu đồ và thông tin quan trọng khác, sau đó lắp ghép thành một trang chủ wiki mạch lạc.

Wiki giờ có mục lục đúng chuẩn, phần giải thích về trợ lý và công cụ, cùng hướng dẫn “bắt đầu” rõ ràng.

Cuối phiên chạy, phần tóm tắt cho thấy phiên duy nhất này tốn gần 1 USD, khá đắt để tạo một wiki 3 trang. Nếu kho lớn hơn và chúng ta cần, ví dụ, wiki 12 trang, chi phí sẽ tăng đáng kể.

=== Session Summary ===
Total Turns:   1
Duration:      282.99s
Total Cost:    $0.9047
=======================

Trong lần thử thứ hai, tôi yêu cầu agent tạo wiki cho một kho khác:

create the github wiki for https://github.com/kingabzpro/Issue-Analyzer

Kết quả còn tốt hơn. Wiki được tạo, tại https://github.com/kingabzpro/Issue-Analyzer/wiki, nay có tài liệu đúng chuẩn giải thích dự án làm gì và cách bắt đầu. 

Nó có các bảng được cấu trúc tốt, sơ đồ kiến trúc và các phần cốt lõi khác giúp bạn hiểu toàn bộ dự án trong khoảng năm phút, thay vì mất nhiều ngày đọc mã.

Suy ngẫm cuối

Khi lần đầu nghe nói Opus 4.5 được ca ngợi là mô hình lập trình và agentic tốt nhất thế giới, tôi thực sự hào hứng, đặc biệt vì giá tương đương dòng Sonnet. 

Tuy nhiên, sự hào hứng giảm đi khi tôi nhận ra việc thử nghiệm và xây dựng một ứng dụng nhỏ tiêu tốn khoảng 15 USD phí API.

Opus 4.5 mạnh mẽ nhưng đắt đỏ. Tôi cũng thử tái tạo quy trình tương tự bằng Haiku và Sonnet, nhưng trải nghiệm kém hơn rõ rệt cho tác vụ kiểu agentic và nặng tài liệu như thế này. 

Cả hai thường quay lại dùng công cụ Bash, ngay cả khi tôi yêu cầu rõ ràng họ dùng công cụ MCP để đọc tệp GitHub. Ngoài ra, họ thường mất nhiều thời gian hơn và đi đường vòng để giải quyết vấn đề.

Nếu bạn ưu tiên độ chính xác, độ tin cậy và chất lượng cao trong việc tạo mã và tài liệu, Opus 4.5 chắc chắn đáng cân nhắc. 

Tuy nhiên, nếu trường hợp sử dụng ít quan trọng hơn hoặc bạn rất nhạy cảm với chi phí, bạn có thể gắn bó với Sonnet hoặc thậm chí các mô hình nguồn mở rẻ hơn. Chi phí liên quan đến Opus 4.5 có thể tăng nhanh, đặc biệt với quy trình agentic nhiều bước trên các kho lớn.

Nếu bạn quan tâm đến dự án, bạn có thể tìm toàn bộ mã nguồn tại đây, có thể clone và chạy cục bộ: kingabzpro/GitHub-Wiki-Agent.

Nếu bạn muốn tiếp tục xây dựng AI agent, tôi khuyến nghị xem khóa học Multi-Agent Systems with LangGraph.