Prompt hệ thống của Claude Code: Bài học kỹ thuật cho người xây dựng tác tử

Bài học từ câu lệnh hệ thống của Claude Code mà không cần sao chép câu lệnh

Cụm từ “câu lệnh hệ thống của Claude Code” đã trở thành cách nói ngắn gọn cho câu hỏi “một tác nhân lập trình nghiêm túc chỉ dẫn mô hình hành xử như thế nào?” Đó là câu hỏi sai nếu nó dẫn đến việc đào bới các câu lệnh cũ, nhưng là câu hỏi đúng nếu nó dẫn đến thiết kế tác nhân tốt hơn.

Trong thực tế, câu lệnh hệ thống chỉ là một lớp. Một tác nhân đạt chuẩn triển khai thực tế thường có ít nhất năm lớp kiểm soát phối hợp với nhau:

Sai lầm tôi thấy ở nhiều tác nhân tự xây dựng là gộp tất cả những lớp này vào một câu lệnh lớn. Cách đó hoạt động trong các bản demo. Nó thất bại khi chịu áp lực.

Cách tiếp cận tốt hơn là dùng câu lệnh để giải thích ý định và dùng môi trường thực thi để áp đặt giới hạn năng lực.

Ví dụ, đừng chỉ đưa ra câu lệnh:

Do not delete files unless the user asks.

Biến thao tác xóa thành một công cụ riêng yêu cầu xác nhận:

{
  "name": "delete_file",
  "description": "Delete a file from the workspace.",
  "input_schema": {
    "type": "object",
    "properties": {
      "path": { "type": "string" },
      "reason": { "type": "string" },
      "user_confirmed": { "type": "boolean" }
    },
    "required": ["path", "reason", "user_confirmed"]
  }
}

Sau đó thực thi yêu cầu đó bên ngoài mô hình:

def delete_file(path: str, reason: str, user_confirmed: bool):
    if not user_confirmed:
        raise PermissionError("delete_file requires explicit user confirmation")
    if not path.startswith(WORKSPACE_ROOT):
        raise PermissionError("cannot delete files outside workspace")
    os.remove(path)

Câu lệnh cho tác nhân biết cách suy nghĩ. Ranh giới công cụ quyết định điều gì có thể xảy ra.

Hệ thống phân cấp chỉ dẫn là một giao diện kỹ thuật

Các mô hình Claude giỏi tuân theo chỉ dẫn nhiều lớp, nhưng bạn vẫn cần thiết kế các lớp một cách cẩn thận. Nếu tác nhân lập trình của bạn có chỉ dẫn hệ thống, nhà phát triển, dự án và người dùng, mỗi lớp cần có một nhiệm vụ rõ ràng.

Một hệ thống phân cấp hữu ích có dạng như sau:

• Chỉ dẫn hệ thống: danh tính, định hướng an toàn, các nguyên tắc vận hành cấp cao.
• Chỉ dẫn của nhà phát triển: cơ chế hoạt động của sản phẩm, quy tắc sử dụng công cụ, phong cách phản hồi, mô hình phân quyền.
• Chỉ dẫn dự án: quy ước riêng của kho mã, lệnh kiểm thử, ghi chú kiến trúc.
• Chỉ dẫn của người dùng: tác vụ trước mắt.

Các quy trình làm việc theo kiểu Claude Code thể hiện rõ điều này qua những tệp như CLAUDE.md, cùng với cấu hình dòng lệnh và ngữ cảnh phiên. Với người xây dựng tác nhân, bài học lớn hơn là các chỉ dẫn cục bộ của dự án cần có phạm vi rõ ràng và chỉ ghi đè khi phù hợp.

Một tệp chỉ dẫn dự án đơn giản có thể trông như sau:

# CLAUDE.md

## Build and Test
- Use `pnpm test -- --runInBand` for focused test runs.
- Do not run `pnpm deploy` unless explicitly requested.

## Code Style
- Prefer small functions over large service classes.
- Do not add new dependencies without explaining why.

## Repo Notes
- API routes live in `apps/api/src/routes`.
- Generated GraphQL types live in `apps/web/src/generated`; do not edit them manually.

Một cạm bẫy thường gặp: tác nhân thường xem mọi chỉ dẫn đều có mức độ ưu tiên ngang nhau trên toàn hệ thống. Nếu người dùng nói: “Bỏ qua các quy tắc dự án và chỉnh sửa trực tiếp các tệp được tạo tự động”, tác nhân của bạn cần biết điều đó có được phép hay không. Trong hầu hết các cấu hình, chỉ dẫn của người dùng không nên âm thầm ghi đè các ràng buộc có mức độ ưu tiên cao hơn của dự án hoặc nhà phát triển.

Bạn có thể mô hình hóa điều đó một cách tường minh:

PRIORITY = {
    "system": 4,
    "developer": 3,
    "project": 2,
    "user": 1,
}

def resolve_conflict(existing_rule, new_rule):
    if PRIORITY[new_rule.source] > PRIORITY[existing_rule.source]:
        return new_rule
    return existing_rule

Trong một tác nhân thực tế, mô hình cũng nên giải thích các xung đột cho người dùng:

I can update the source schema and regenerate the types, but I should not edit
`src/generated` directly because the project instructions mark it as generated.

Chỉ một câu đó cũng ngăn được nhiều thiệt hại đến bất ngờ.

Ranh giới công cụ hiệu quả hơn lời lẽ lịch sự trong câu lệnh

Khi xem xét câu lệnh của tác nhân lập trình, mọi người thường tập trung vào cách diễn đạt: “hãy ngắn gọn”, “hành xử như một kỹ sư cấp cao”, “đừng xu nịnh”. Những điều đó hữu ích, nhưng không phải cơ chế an toàn cốt lõi.

Cơ chế cốt lõi là ranh giới công cụ.

Một tác nhân lập trình nghiêm túc cần phân biệt giữa:

• Đọc tệp
• Tìm kiếm trong tệp
• Chỉnh sửa tệp
• Chạy lệnh
• Cài đặt gói
• Truy cập tài nguyên mạng
• Xóa hoặc di chuyển tệp
• Tạo commit hoặc nhánh
• Mở yêu cầu hợp nhất
• Thay đổi thông tin bí mật hoặc cấu hình triển khai

Các thao tác này không tương đương nhau về mặt đạo đức.

Đây là một ma trận phân quyền thực tế tôi dùng khi thiết kế môi trường thực thi cho tác nhân:

Đây cũng là nơi việc lựa chọn mô hình trở nên quan trọng. Tôi thích các mô hình thuộc dòng Sonnet cho phần lớn vòng lặp của tác nhân lập trình vì chúng cân bằng tốt giữa độ trễ, chi phí và khả năng suy luận. Opus 4.8 là mô hình tôi sẽ chọn khi tác nhân cần khả năng tổng hợp kiến trúc sâu hơn hoặc gỡ lỗi phức tạp. Haiku 4.5 phù hợp với việc phân loại nhanh và quét kho mã ở mức nhẹ. Ngữ cảnh 1M của Fable 5 đáng chú ý đối với việc hiểu các cơ sở mã lớn, nhưng ngữ cảnh dài không loại bỏ nhu cầu truy xuất tốt, đọc trong phạm vi giới hạn và sử dụng công cụ có kỷ luật.

Một triệu token ngữ cảnh vẫn có thể chứa nhầm tệp.

Xác nhận của người dùng cần cụ thể, không mang tính hình thức

Trải nghiệm xác nhận kém có dạng như sau:

May I proceed?

Tiếp tục việc gì? Chỉnh sửa một tệp? Chạy migration? Xóa một thư mục?

Xác nhận tốt phải cụ thể:

I need confirmation before running:

`rm -rf apps/web/.next`

Reason: remove a stale Next.js build cache that may be causing the local
runtime error. This deletes only generated build output and does not touch
source files.

Với các tác tử giống Claude Code, điều này quan trọng vì mô hình có thể suy luận đúng bước tiếp theo nhưng vẫn cần sự cho phép của con người. Nếu mọi lời nhắc đều yêu cầu phê duyệt mơ hồ, người dùng sẽ mệt mỏi vì phải phê duyệt và cứ bấm cho qua. Nếu chỉ các thao tác rủi ro cao mới yêu cầu xác nhận chính xác, người dùng sẽ tiếp tục chú ý.

Tôi khuyên nên biểu diễn việc xác nhận bằng trạng thái có cấu trúc, thay vì văn bản diễn giải:

{
  "action": "run_shell",
  "command": "rm -rf apps/web/.next",
  "risk": "destructive_generated_artifact",
  "requires_confirmation": true,
  "confirmation_prompt": "Delete generated Next.js cache at apps/web/.next?"
}

Sau đó, trình chạy lệnh shell của bạn có thể thực thi yêu cầu này:

def run_shell(command, confirmed=False):
    risk = classify_command(command)

    if risk.requires_confirmation and not confirmed:
        return {
            "status": "needs_confirmation",
            "message": risk.prompt
        }

    return subprocess.run(command, shell=True, cwd=WORKSPACE_ROOT)

Trong thực tế, việc phân loại lệnh sẽ không bao giờ hoàn hảo. Điều đó không sao. Hãy dùng các giá trị mặc định thận trọng. Nếu bộ phân loại không chắc một lệnh có gây phá hủy hay không, hãy hỏi.

Những lệnh cần xử lý thận trọng

Những lệnh này cần có chính sách rõ ràng:

rm -rf path
git reset --hard
git clean -fd
git push --force
npm install some-package
pip install -r requirements.txt
docker compose down -v
kubectl delete ...
terraform apply

Một số lệnh vô hại trong đúng bối cảnh. Một số lại gây hậu quả thảm khốc trong bối cảnh sai. Tác tử cần hiểu rằng sự khác biệt phụ thuộc vào bối cảnh và hỏi khi phạm vi ảnh hưởng chưa rõ.

Truy cập tệp là một phần của kỹ thuật thiết kế ngữ cảnh

Phần bị đánh giá thấp nhất trong thiết kế tác tử lập trình là truy cập tệp. Lời nhắc có thể nói “hãy kiểm tra các tệp liên quan trước”, nhưng môi trường thực thi cần giúp hành vi đó trở nên dễ dàng.

Tối thiểu, hãy cung cấp cho mô hình các công cụ để:

• Tìm nhanh tên tệp
• Tìm kiếm văn bản
• Đọc các phạm vi giới hạn trong tệp
• Xem diff của git
• Áp dụng bản vá theo cách nguyên tử

Một bộ công cụ tối thiểu có thể như sau:

[
  {
    "name": "search_files",
    "input_schema": {
      "type": "object",
      "properties": {
        "query": { "type": "string" },
        "glob": { "type": "string" }
      },
      "required": ["query"]
    }
  },
  {
    "name": "read_file",
    "input_schema": {
      "type": "object",
      "properties": {
        "path": { "type": "string" },
        "start_line": { "type": "integer" },
        "limit": { "type": "integer" }
      },
      "required": ["path"]
    }
  },
  {
    "name": "apply_patch",
    "input_schema": {
      "type": "object",
      "properties": {
        "patch": { "type": "string" }
      },
      "required": ["patch"]
    }
  }
]

Việc giới hạn phạm vi đọc rất quan trọng. Nếu tác tử đọc mọi tệp trong một monorepo, nó sẽ lãng phí ngữ cảnh và thường hoạt động kém hơn. Nếu đọc quá ít, nó sẽ đoán. Điểm cân bằng là thu thập ngữ cảnh theo từng vòng:

rg "createSession|verifySession|SessionStore" apps packages
sed -n '1,220p' apps/api/src/auth/session.ts
sed -n '1,180p' apps/api/src/routes/login.ts
git diff -- apps/api/src/auth/session.ts

Người dùng Claude Code sẽ nhận ra nhịp làm việc này: tìm kiếm, kiểm tra, chỉnh sửa, xác minh. Người xây dựng tác tử nên đưa vòng lặp đó vào hành vi mặc định.

Một cạm bẫy thường gặp: công cụ xử lý tệp cần giữ nguyên ký tự kết thúc dòng, quyền truy cập và các yêu cầu về mã hóa. Tôi từng thấy tác tử viết lại tập lệnh shell một cách “thành công” nhưng lại xóa bit quyền thực thi, hoặc chuẩn hóa tệp theo cách tạo ra các diff nhiễu. Lớp chỉnh sửa của bạn nên đơn giản và thận trọng.

Các dạng thất bại: Điều thực sự xảy ra khi tác tử gặp lỗi

Phần lớn tác tử lập trình không thất bại theo cách rõ ràng, nghiêm trọng. Chúng thất bại theo cách trông có vẻ hợp lý.

Dưới đây là những dạng thất bại tôi gặp thường xuyên nhất.

1. Tác tử chỉ xử lý triệu chứng

Kiểm thử thất bại vì một API trả về 401. Tác tử sửa kiểm thử để mong đợi 401. Bản dựng đạt, sản phẩm hỏng.

Biện pháp giảm thiểu:

• Yêu cầu tác tử giải thích chuỗi nguyên nhân và kết quả.
• Yêu cầu các kiểm thử tập trung trước khi viết lại trên diện rộng.
• Ưu tiên sửa mã nguồn hơn cập nhật snapshot, trừ khi người dùng yêu cầu thay đổi hành vi.

2. Tác tử chỉnh sửa quá mức

Người dùng yêu cầu sửa một lỗi nhỏ. Tác tử định dạng lại năm tệp, đổi tên biến và thay đổi các API công khai.

Biện pháp giảm thiểu:

Make the minimal change that fixes the issue. Do not perform opportunistic
refactors unless they are necessary for correctness.

Nhưng cũng cần bắt buộc rà soát diff. Hiển thị các tệp đã thay đổi và số dòng trước khi hoàn tất:

git diff --stat
git diff -- apps/api/src/auth/session.ts

3. Tác tử tin vào ngữ cảnh lỗi thời

Các phiên chạy dài tích lũy những giả định lỗi thời. Người dùng thay đổi một tệp bên ngoài phiên, các kiểm thử giờ thất bại theo cách khác, nhưng tác tử vẫn tiếp tục dựa trên cách hiểu cũ.

Biện pháp giảm thiểu:

• Đọc lại các tệp trước khi chỉnh sửa nếu chúng có thể đã thay đổi.
• Kiểm tra git diff trước khi áp dụng bản vá.
• Xem đầu ra của công cụ là thông tin mới hơn bộ nhớ hội thoại.

4. Tác tử che giấu lỗi công cụ

Một lệnh shell thất bại, nhưng tác tử vẫn tiếp tục như thể lệnh đã thành công.

Biện pháp giảm thiểu: kết quả công cụ cần có cấu trúc và khó bị bỏ qua.

{
  "tool": "run_shell",
  "command": "pnpm test auth",
  "exit_code": 1,
  "stdout": "...",
  "stderr": "Cannot find module '@repo/config'",
  "status": "failed"
}

Sau đó, hướng dẫn tác tử:

If a tool call fails, do not claim success. Diagnose the failure or clearly
report the blocker.

5. Tác tử đưa thông tin bí mật vào ngữ cảnh

Nếu tác tử có thể đọc .env, bản kết xuất khi gặp sự cố hoặc cấu hình môi trường production, nó có thể vô tình đưa thông tin bí mật vào bản tóm tắt, nhật ký hoặc lời nhắc.

Biện pháp giảm thiểu:

• Mặc định chặn các tệp đã biết là chứa thông tin bí mật.
• Che các giá trị có dạng token trong đầu ra của công cụ.
• Yêu cầu người dùng phê duyệt rõ ràng đối với các đường dẫn chứa thông tin bí mật.

Ví dụ về chính sách đường dẫn:

DENY_PATTERNS = [
    ".env",
    ".env.*",
    "**/secrets/**",
    "**/*.pem",
    "**/*.key",
]

def can_read(path):
    return not any(fnmatch(path, pattern) for pattern in DENY_PATTERNS)

Nhắc mô hình không làm lộ thông tin bí mật là tốt. Ngăn mô hình nhìn thấy những thông tin bí mật không cần thiết còn tốt hơn.

Thiết kế vòng lặp tác tử dùng Claude API

Nếu bạn xây dựng trực tiếp trên Claude API, vòng lặp hữu ích đơn giản nhất là:

1. Gửi chỉ dẫn hệ thống và chỉ dẫn dành cho nhà phát triển.
2. Cung cấp nhiệm vụ của người dùng.
3. Để Claude yêu cầu sử dụng công cụ.
4. Thực thi công cụ trong môi trường thực thi của bạn.
5. Trả về kết quả công cụ.
6. Lặp lại cho đến khi mô hình tạo ra câu trả lời cuối cùng.

Cấu trúc yêu cầu đơn giản hóa có dạng như sau:

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 4096,
  "system": "You are a coding agent. Make minimal, correct changes...",
  "messages": [
    {
      "role": "user",
      "content": "Fix the auth timeout bug and add a regression test."
    }
  ],
  "tools": [
    {
      "name": "read_file",
      "description": "Read a bounded section of a workspace file.",
      "input_schema": {
        "type": "object",
        "properties": {
          "path": { "type": "string" },
          "start_line": { "type": "integer" },
          "limit": { "type": "integer" }
        },
        "required": ["path"]
      }
    }
  ]
}

Về mặt khái niệm, phản hồi sử dụng công cụ có dạng như sau:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I’ll inspect the auth timeout path first."
    },
    {
      "type": "tool_use",
      "name": "read_file",
      "id": "toolu_123",
      "input": {
        "path": "apps/api/src/auth/session.ts",
        "start_line": 1,
        "limit": 220
      }
    }
  ]
}

Sau đó, môi trường thực thi của bạn trả về kết quả:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_123",
      "content": "export function createSession(...) { ... }"
    }
  ]
}

Cú pháp SDK chính xác phụ thuộc vào phiên bản thư viện máy khách của bạn, nhưng nguyên tắc thiết kế vẫn ổn định: Claude đề xuất hành động, môi trường thực thi của bạn thực hiện hoặc từ chối chúng, và lượt tiếp theo của mô hình nhận được kết quả.

Chính sự tách biệt đó giúp hệ thống dễ hiểu.

Các lệnh và thiết lập của Claude Code đáng nghiên cứu

Ngay cả khi không trực tiếp sử dụng Claude Code, quy trình làm việc của nó vẫn cung cấp những mẫu thiết kế sản phẩm hữu ích.

Quy trình khởi tạo dự án điển hình:

claude
/init

Thao tác đó tạo hoặc cập nhật hướng dẫn dự án để các phiên sau hiểu được những quy ước riêng của kho mã.

Một phiên làm việc thực tế thường có dạng như sau:

claude "Find why the billing webhook test is flaky. Do not edit files yet."
claude "Patch the smallest fix and run the focused test."
claude "Show me the diff and summarize remaining risks."

Tôi thích cách này vì nó tách biệt việc tìm hiểu, thay đổi và xác minh. Người xây dựng tác tử có thể mô phỏng điều đó bằng các chế độ:

{
  "mode": "investigate",
  "can_edit": false,
  "can_run_tests": true,
  "requires_confirmation_for": ["network", "delete", "install"]
}

Sau đó chuyển chế độ một cách rõ ràng:

{
  "mode": "implement",
  "can_edit": true,
  "can_run_tests": true,
  "requires_confirmation_for": ["network", "delete", "install", "commit"]
}

Điều quan trọng không phải là lệnh cụ thể, mà là quy ước tương tác. Người dùng cần biết khi nào tác tử chỉ đang đọc, khi nào đang thay đổi tệp và khi nào sắp thực hiện việc có tác động ngoài việc đọc.

Vì sao các bản trích xuất lời nhắc dễ mất hiệu quả

Kho mã GitHub thu thập các lời nhắc hệ thống và cấu hình mô hình trở nên phổ biến vì các kỹ sư vốn tò mò về cách những công cụ thực tế được chỉ dẫn. Tôi hiểu sức hấp dẫn đó. Đọc lời nhắc có thể cho thấy quan điểm thiết kế sản phẩm: người xây dựng lo ngại những rủi ro nào, họ tối ưu quy trình nào và họ giao tiếp với mô hình ra sao.

Nhưng các lời nhắc sao chép dễ mất hiệu quả vì một số lý do:

• Chúng có thể không phải bản chính thức. Bạn có thể không biết chúng được trích xuất như thế nào hoặc có đầy đủ hay không.
• Chúng có thể đã lỗi thời. Lời nhắc cho tác tử thay đổi khi mô hình, công cụ và chính sách sản phẩm thay đổi.
• Chúng phụ thuộc vào hành vi ẩn của môi trường thực thi. Một lời nhắc đề cập đến công cụ sẽ vô dụng nếu không có phần triển khai công cụ đó.
• Chúng thể hiện những đánh đổi riêng của sản phẩm. Các ràng buộc của Claude Code có thể không phù hợp với mô hình mối đe dọa của tác tử bạn xây dựng.
• Chúng có thể tạo ra sự tự tin sai lầm. Một lời nhắc được trau chuốt không thực thi quyền truy cập.

Hãy dùng những tài liệu này làm nguồn cảm hứng thiết kế, không phải thành phần phụ thuộc.

Một cách thực hành tốt hơn là hỏi: chỉ dẫn này đang giải quyết vấn đề gì? Sau đó giải quyết vấn đề đó trong hệ thống công nghệ của riêng bạn, với sự hỗ trợ từ cả lời nhắc lẫn môi trường thực thi.

Những điểm thực tiễn cần ghi nhớ

• Hãy xem cuộc thảo luận về Claude Code system prompt là một cuộc thảo luận về kiến trúc, không phải cơ hội để sao chép và dán.
• Đặt hành vi ổn định trong chỉ dẫn hệ thống hoặc chỉ dẫn dành cho nhà phát triển, quy ước kho mã trong tệp dự án và mục tiêu nhiệm vụ trong tin nhắn của người dùng.
• Thực thi các giới hạn đối với thao tác rủi ro cao thông qua công cụ và quyền của môi trường thực thi, không chỉ bằng văn bản diễn giải.
• Yêu cầu xác nhận cụ thể cho các hành động gây phá hủy, sử dụng mạng, thay đổi thành phần phụ thuộc hoặc ảnh hưởng đến môi trường production.
• Cung cấp cho tác tử khả năng truy cập tệp có giới hạn, tìm kiếm nhanh, áp dụng bản vá nguyên tử và thông tin lỗi công cụ có cấu trúc.
• Tối ưu cho vòng lặp hiệu quả trong thực tế: kiểm tra, lập kế hoạch, chỉnh sửa tối thiểu, xác minh, tóm tắt rủi ro.
• Giả định rằng các lời nhắc sao chép có thể đã lỗi thời hoặc không đầy đủ; xây dựng hành vi tác tử bền vững dựa trên các khả năng được xác định rõ và cách xử lý lỗi minh bạch.