Chuyển tới nội dung chính

Báo cáo nghiên cứu sâu về mã nguồn Claude Code

1. Phạm vi nghiên cứu và kết luận tổng quát​

1.1 Lần này thực sự nghiên cứu những gì​

Nghiên cứu này không chỉ đọc một file prompt đơn lẻ hoặc lướt qua cấu trúc thư mục. Nó khôi phục mã nguồn từ sourcesContent trong cli.js.map, rồi phân tích theo đúng luồng runtime thực tế.

Các chủ đề chính gồm:

  • cấu trúc tổng thể của Claude Code
  • cách main system prompt được lắp ghép động
  • giao thức phía model của AgentTool và SkillTool
  • sự phân công vai trò của built-in agents
  • chuỗi orchestration của agent
  • cách plugins, skills, hooks và MCP đi vào runtime
  • cách permissions, tool execution và hook decisions phối hợp với nhau
  • vì sao Claude Code mạnh hơn hẳn kiểu “LLM + tool caller” thông thường

1.2 Các sự thật đã được xác nhận​

Có thể xác nhận ít nhất các điểm sau:

  1. cli.js.map chứa đầy đủ sourcesContent
  2. ít nhất 4756 file mã nguồn đã được khôi phục
  3. file trung tâm của main system prompt là src/constants/prompts.ts
  4. Agent Tool Prompt nằm trong src/tools/AgentTool/prompt.ts
  5. Skill Tool Prompt nằm trong src/tools/SkillTool/prompt.ts
  6. lõi orchestration của agent bao gồm src/tools/AgentTool/AgentTool.tsx và src/tools/AgentTool/runAgent.ts
  7. chuỗi thực thi công cụ dựa nhiều vào src/services/tools/toolExecution.ts và src/services/tools/toolHooks.ts

1.3 Kết luận quan trọng nhất ngay từ đầu​

Điểm mạnh của Claude Code không đến từ một system prompt bí ẩn, mà đến từ một hệ thống phần mềm hoàn chỉnh.

Sức mạnh đó đến từ việc kết hợp:

  • prompt assembly dạng module
  • thực thi công cụ có governance
  • permission model
  • agent chuyên biệt hóa
  • đóng gói workflow bằng skills
  • plugin metadata và runtime constraints
  • hooks như policy layer
  • MCP vừa bơm capability vừa bơm usage guidance
  • xây prompt có ý thức về cache
  • quản lý vòng đời cho tác vụ async và background

Tóm gọn trong một câu:

Claude Code không phải là một prompt. Nó là một Agent Operating System hợp nhất prompts, tools, permissions, agents, skills, plugins, hooks, MCP, cache và runtime cấp sản phẩm.

2. Kiến trúc mã nguồn: vì sao nó giống Agent Operating System​

2.1 Cấu trúc top-level đã cho thấy độ phức tạp hệ thống​

Trong src/ có các module như:

  • src/entrypoints/
  • src/constants/
  • src/tools/
  • src/services/
  • src/utils/
  • src/commands/
  • src/components/
  • src/coordinator/
  • src/memdir/
  • src/plugins/
  • src/hooks/
  • src/bootstrap/
  • src/tasks/

Đây là một runtime platform hoàn chỉnh, không phải lớp CLI mỏng.

2.2 Lớp entry cho thấy tư duy nền tảng​

Các entrypoint nhìn thấy được:

  • src/entrypoints/cli.tsx
  • src/entrypoints/init.ts
  • src/entrypoints/mcp.ts
  • src/entrypoints/sdk/

Tức là cùng một agent runtime phục vụ CLI, init flow, MCP mode và SDK consumers.

2.3 Hệ thống command là control plane​

Các command nổi bật gồm:

  • /mcp
  • /memory
  • /permissions
  • /hooks
  • /plugin
  • /reload-plugins
  • /skills
  • /tasks
  • /plan
  • /review
  • /status
  • /model
  • /output-style
  • /agents
  • /sandbox-toggle

Nó còn nạp cả plugin commands, skill commands, bundled skills và dynamic skills. Command system chính là cổng vào của hệ sinh thái.

2.4 Tầng tools biến model thành executor​

Những tool quan trọng gồm:

  • FileRead
  • FileEdit
  • FileWrite
  • Bash
  • Glob
  • Grep
  • TodoWrite
  • TaskCreate
  • AskUserQuestion
  • Skill
  • Agent
  • MCPTool
  • Sleep

Chính tầng này biến model từ responder thành actor.

3. Vai trò thật sự của prompts.ts​

3.1 src/constants/prompts.ts là điểm điều khiển trung tâm​

File này quan trọng vì nó lắp ghép các chỉ dẫn runtime cho main thread.

Nó phụ trách:

  • main system prompt assembly
  • tiêm thông tin môi trường
  • quy tắc dùng công cụ
  • quy tắc hành động rủi ro
  • session-specific guidance
  • ngôn ngữ và output style
  • MCP instructions
  • memory prompt
  • scratchpad
  • function result clearing
  • các section có feature gate như brief mode hay token budget

3.2 getSystemPrompt() là orchestrator​

Thiết kế chính là tách thành static prefix và dynamic suffix.

Static prefix:

  • getSimpleIntroSection()
  • getSimpleSystemSection()
  • getSimpleDoingTasksSection()
  • getActionsSection()
  • getUsingYourToolsSection()
  • getSimpleToneAndStyleSection()
  • getOutputEfficiencySection()

Dynamic suffix:

  • session guidance
  • memory
  • model override
  • env info
  • language
  • output style
  • MCP instructions
  • scratchpad
  • function result clearing
  • summarize tool results
  • numeric anchors
  • token budget
  • brief mode

Claude Code xem prompt như runtime resource có thể lắp ghép.

3.3 Prompt cache boundary cho thấy tư duy hạ tầng​

Một ranh giới như SYSTEM_PROMPT_DYNAMIC_BOUNDARY cho thấy mục tiêu là:

  • giữ prefix thân thiện với cache
  • đẩy nội dung theo user/session xuống phía sau
  • tránh phá hỏng cache behavior

Đây là prompt assembly gắn với cache economics.

4. Phân rã các section của prompt​

4.1 getSimpleIntroSection()​

Section này xác lập rằng:

  • Claude là interactive agent
  • nhiệm vụ là hỗ trợ software engineering
  • output style do bên ngoài điều khiển
  • cyber-risk guidance được tiêm ngay từ đầu
  • không được đoán hoặc bịa URL

4.2 getSimpleSystemSection()​

Nó định nghĩa runtime reality:

  • output không phải tool sẽ hiển thị trực tiếp cho người dùng
  • tools chạy dưới permission modes
  • tool bị từ chối không được retry y nguyên
  • kết quả có thể chứa <system-reminder>
  • tool output bên ngoài có thể chứa prompt injection
  • hooks tồn tại
  • context có thể bị nén tự động

4.3 getSimpleDoingTasksSection()​

Section này ổn định hành vi của model:

  • không thêm tính năng không được yêu cầu
  • không over-abstract
  • không refactor vô cớ
  • không thêm comments, docstrings hay type annotations không cần thiết
  • không thêm fallback hoặc validation thừa
  • không xây future-proof abstraction mang tính suy đoán
  • đọc rồi mới sửa
  • tránh tạo file mới khi không cần
  • tránh ước lượng thời gian tùy tiện
  • chẩn đoán trước khi đổi chiến lược
  • chú ý bảo mật
  • xóa phần thực sự không cần thiết
  • báo cáo trung thực những gì đã verify

4.4 getActionsSection()​

Các hành động phải xác nhận gồm:

  • destructive operations
  • hard-to-reverse operations
  • thay đổi shared state
  • hành động lộ ra bên ngoài
  • upload sang công cụ bên thứ ba

4.5 getUsingYourToolsSection()​

Tool usage grammar rất rõ ràng:

  • đọc bằng FileRead
  • sửa bằng FileEdit
  • tạo mới bằng FileWrite
  • tìm file bằng Glob
  • tìm nội dung bằng Grep
  • giữ Bash cho nhu cầu shell thực sự
  • dùng TodoWrite / TaskCreate khi có
  • song song hóa các lời gọi độc lập

4.6 Session-specific guidance​

Lớp động này tiêm các quy tắc cục bộ theo trạng thái phiên làm việc: AskUserQuestion, AgentTool, Explore / Plan agents, slash skills, DiscoverSkills, verification contract.

4.7 Output efficiency​

Mục tiêu là:

  • người dùng nhận ngôn ngữ tự nhiên, không phải log
  • nói action hoặc conclusion trước
  • cập nhật khi cần nhưng không dài dòng
  • tránh bảng biểu vô ích
  • viết ngắn và trực diện

4.8 Tone and style​

Những chi tiết như không lạm dụng emoji, trả lời ngắn gọn, trích dẫn code bằng file_path:line_number góp phần lớn vào cảm giác sản phẩm.

4.9 DEFAULT_AGENT_PROMPT​

Vai trò nền của sub-agent là:

  • là một Claude Code agent
  • dùng tools để hoàn thành task
  • không trả về kết quả dang dở
  • cuối cùng phải báo cáo ngắn gọn

5. Agent prompts và built-in agents​

5.1 AgentTool/prompt.ts là tài liệu giao thức​

File này giải thích cho model:

  • agent list được hiển thị thế nào
  • mô tả mỗi agent ra sao
  • khi nào nên tự fork
  • khi nào cần subagent_type
  • khác biệt giữa fork và fresh agent
  • khi nào không nên dùng AgentTool
  • cách viết prompt cho sub-agent
  • khác biệt foreground / background
  • ý nghĩa của worktree / remote isolation

5.2 Vì sao fork semantics mạnh​

Khi fork được bật:

  • bỏ subagent_type nghĩa là self-fork
  • fork kế thừa toàn bộ context
  • research task rất hợp với fork
  • implementation task có nhiều output trung gian cũng hợp
  • fork rẻ hơn nhờ chia sẻ prompt cache
  • đổi model làm xấu cache reuse
  • main thread không nên nhìn trộm output của fork
  • main thread không nên đoán trước kết quả

5.3 Phần “How to write the prompt” rất có giá trị​

Model được dạy cách delegation tốt:

  • fresh agent không có context cũ
  • prompt phải giống briefing cho đồng đội mới
  • nêu rõ goal và reason
  • nói những gì đã loại trừ
  • cung cấp đủ bối cảnh
  • muốn câu trả lời ngắn thì phải nói rõ
  • không outsource việc hiểu bài toán
  • không delegation lười
  • đưa file path, line và yêu cầu thay đổi cụ thể

5.4 Built-in agents thể hiện specialization​

Các role được xác nhận gồm:

  • General Purpose Agent
  • Explore Agent
  • Plan Agent
  • Verification Agent
  • Claude Code Guide Agent
  • Statusline Setup Agent

5.5 Explore Agent là read-only specialist​

Explore không được tạo, sửa, xóa hay di chuyển file. Nó dùng Glob, Grep, FileRead và chỉ dùng Bash ở chế độ read-only, ưu tiên tốc độ và song song hóa.

5.6 Plan Agent là pure planner​

Plan giữ read-only, hiểu yêu cầu, khám phá codebase và trả về implementation plan từng bước cùng Critical Files for Implementation.

5.7 Verification Agent là adversarial validator​

Verification agent phải cố gắng phá vỡ thay đổi. Nó yêu cầu:

  • build
  • test suite
  • lint / type-check
  • kiểm tra chuyên biệt theo loại thay đổi
  • browser automation cho frontend
  • curl / fetch cho backend
  • stdout / stderr / exit code cho CLI
  • migration up/down
  • kiểm tra public API
  • adversarial probes
  • command và observed output
  • VERDICT: PASS / FAIL / PARTIAL

6. Chuỗi orchestration của agent​

6.1 Luồng tổng thể​

Luồng chính có thể tóm tắt như sau:

  1. main model gọi Agent tool
  2. AgentTool.call() phân tích input
  3. resolve fork / built-in / teammate / background / remote
  4. chọn agent definition
  5. xây prompt messages
  6. xây hoặc kế thừa system prompt
  7. tạo tool pool
  8. tạo ToolUseContext riêng cho agent
  9. đăng ký hooks, skills và MCP servers
  10. gọi runAgent()
  11. query() chạy main loop
  12. xử lý transcript, metadata và cleanup

6.2 AgentTool.call() là orchestration controller​

Nó xử lý parse input, team context, quyền chạy background, tách fork path và normal path, lọc agents bằng permissions, kiểm tra MCP, xây prompts, đăng ký tasks và gọi runAgent().

6.3 fork path vs normal path​

fork path ưu tiên kế thừa context và reuse prompt cache. normal path tạo agent system prompt mới, chỉ truyền context cần thiết và áp dụng tool restrictions riêng.

6.4 Vì sao cache-identical prefix quan trọng​

Mục tiêu là giữ request prefix càng giống nhau càng tốt để tăng prompt cache hit và giảm chi phí token.

6.5 Foreground và background lifecycle​

Background agents có abort controller riêng, task registration và quay lại bằng notification. Foreground agents bám sát main thread hơn và có progress tracking.

6.6 runAgent() là runtime constructor​

runAgent() khởi tạo MCP servers riêng, chuẩn bị context, resolve tools và permissions, đăng ký hooks và skills, gọi query() và cleanup tài nguyên.

6.7 Agent-specific MCP servers​

Agent có thể mang theo MCP servers riêng để bơm năng lực chuyên biệt vào runtime.

6.8 Frontmatter hooks và frontmatter skills​

Hooks và skills có thể được gắn vào agent qua frontmatter. Agent vì thế là một prompt container có thể cấu hình.

6.9 query() là main loop cuối cùng​

Phân lớp rất rõ:

  • AgentTool định tuyến
  • runAgent dựng runtime và lifecycle
  • query chạy vòng lặp model + tools

6.10 transcript / metadata / cleanup​

Việc ghi transcript, metadata, tracking và dọn dẹp cho thấy runtime của sub-agent đã được productize rất sâu.

7. Skills / Plugins / Hooks / MCP​

7.1 Skill là workflow package​

Skill là primitive hạng nhất. Nếu task khớp với skill, model phải gọi Skill tool chứ không chỉ nhắc đến skill.

7.2 Plugin là prompt + metadata + runtime constraints​

Plugin có thể cung cấp markdown commands, SKILL.md, metadata, allowed tools, model hints và runtime variables. Nó mở rộng hành vi của model.

7.3 Hook là runtime governance layer​

PreToolUse, PostToolUse, PostToolUseFailure có thể trả về message, blocking error, updated input, permission behavior hoặc additional context.

7.4 Hook và permission model tích hợp chặt chẽ​

Hooks có thể trả về allow, ask, deny, nhưng không bypass mô hình an toàn trung tâm.

7.5 MCP là lớp tiêm hành vi​

MCP không chỉ thêm tool mà còn thêm hướng dẫn cách dùng tool.

8. Permissions, hooks và tool execution pipeline​

8.1 toolExecution.ts​

Pipeline gồm: lookup tool, parse metadata, validate schema, validate theo tool, hooks, quyết định permission, gọi tool, telemetry và post-hooks.

8.2 Input validation​

Các lỗi cơ bản bị chặn sớm bằng schema parsing và validation riêng của tool.

8.3 PreToolUse hooks​

Ba trường quan trọng nhất là updatedInput, permissionBehavior và preventContinuation.

8.4 resolveHookPermissionDecision()​

Logic này nối ngữ nghĩa của hook với permission model trung tâm.

8.5 Governance vẫn tiếp tục sau tool call​

Ngay cả sau thành công hoặc thất bại, hooks vẫn có thể bơm context, chặn bước tiếp theo hoặc đưa gợi ý khôi phục.

9. Vì sao Claude Code mạnh​

9.1 Nó không phải prompt, mà là operating model​

Lợi thế thật sự nằm ở việc tích hợp prompt architecture, governed runtime, permissions, hooks, specialization, skills, plugins, MCP, cache và lifecycle management.

9.2 Nó thể chế hóa hành vi tốt​

Claude Code không để model tự ứng biến thói quen tốt; nó viết các thói quen đó vào prompts và runtime rules.

9.3 Nó hiểu context là tài nguyên khan hiếm​

Prompt boundaries, cache reuse, on-demand injection, result clearing và resume mechanisms cho thấy token được quản lý như budget.

9.4 Specialization của agent là lợi thế sâu​

Explore, Plan và Verification tách rời nghiên cứu, lập kế hoạch, triển khai và xác minh.

9.5 Hệ sinh thái là model-aware​

Model biết skill lists, agent lists, MCP instructions và session-specific guidance của chính nó. Vì vậy hệ sinh thái mới thực sự hoạt động.

10. Các file quan trọng và hướng đào sâu tiếp theo​

10.1 Prompt files​

  • src/constants/prompts.ts
  • src/tools/AgentTool/prompt.ts
  • src/tools/SkillTool/prompt.ts
  • src/tools/FileReadTool/prompt.ts
  • src/tools/GlobTool/prompt.ts
  • src/tools/GrepTool/prompt.ts
  • src/tools/BriefTool/prompt.ts

10.2 Agent files​

  • src/tools/AgentTool/AgentTool.tsx
  • src/tools/AgentTool/runAgent.ts
  • src/tools/AgentTool/resumeAgent.ts
  • src/tools/AgentTool/forkSubagent.ts
  • src/tools/AgentTool/agentMemory.ts
  • src/tools/AgentTool/agentMemorySnapshot.ts
  • src/tools/AgentTool/builtInAgents.ts
  • src/tools/AgentTool/built-in/exploreAgent.ts
  • src/tools/AgentTool/built-in/planAgent.ts
  • src/tools/AgentTool/built-in/verificationAgent.ts
  • src/tools/AgentTool/built-in/generalPurposeAgent.ts
  • src/tools/AgentTool/built-in/claudeCodeGuideAgent.ts
  • src/tools/AgentTool/built-in/statuslineSetup.ts

10.3 Skill / Plugin / Hook / MCP​

  • src/tools/SkillTool/constants.ts
  • src/tools/SkillTool/prompt.ts
  • src/commands.ts
  • src/utils/plugins/loadPluginCommands.ts
  • src/services/tools/toolHooks.ts
  • src/utils/hooks.js
  • src/services/tools/toolExecution.ts
  • src/services/mcp/types.ts
  • src/services/mcp/normalization.ts
  • src/services/mcp/mcpStringUtils.ts
  • src/services/mcp/utils.ts
  • src/entrypoints/mcp.ts

10.4 Các hướng đào sâu tiếp theo​

  1. query.ts
  2. resumeAgent.ts
  3. loadSkillsDir
  4. plugin loading
  5. systemPromptSections.ts
  6. coordinator/*
  7. attachments.ts
  8. AgentSummary

Kết luận​

Nếu chỉ giữ lại một câu, thì đó là:

Bí mật thật sự của Claude Code không phải là một system prompt, mà là một hệ thống hợp nhất prompt architecture, tool runtime, permission model, agent orchestration, skill packaging, plugin system, hook governance, MCP integration, context hygiene và product engineering.

Vì vậy Claude Code không giống một chatbot biết gọi tool, mà giống một Agent Operating System có thể mở rộng và có thể quản trị.