- 人工智能
- 大模型
- AI Agent
- 代码智能体
- 工具调用
- 交互助手
- CLI
【免费下载链接】kilocode
Kilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.
Kilo Code 的自定义指令（Custom Instructions）机制允许开发者在不改动模型本身的前提下，通过文件与配置精准塑造 Agent 的编码风格、文档规范、测试要求与决策流程。本文将系统讲解 VSCode 与 CLI 两种形态下的全部指令来源——从 Settings UI 中的按 Agent 提示词、项目根目录自动发现的AGENTS.md，到全局配置目录与kilo.jsonc的instructions数组——并结合仓库源码剖析指令的向上查找、聚合注入与动态更新原理，帮助读者搭建一套可落地、可维护的多层级指令体系。
什么是自定义指令？
Custom Instructions 定义了超出 Kilo 基础角色设定（role definition）之外的扩展行为、偏好与约束。典型场景包括：
- 编码风格：缩进宽度、命名规范、是否严格遵循 PEP8 等；
- 文档标准：注释格式、README 维护要求、API 文档写作规范；
- 测试要求：单元测试覆盖范围、测试框架选择、测试结构约定；
- 工作流指南：代码评审流程、提交信息规范、禁止访问的敏感文件。
自定义指令的落地方式不是单一入口，而是"多层叠加"：从 Settings UI 中每个 Agent 自己的提示词，到项目内自动发现的指令文件，再到跨项目生效的全局配置，最后还有kilo.jsonc中显式引用的补充规则源。VSCode 与 CLI 两个形态都支持这套机制，但各自的具体配置入口不同。
指令配置的多层来源总览
| 来源 | 作用域 | 位置 | 优先级 |
|---|---|---|---|
| Agent 提示词 | 按 Agent | agent.<name>.prompt（配置）或 Agent 定义文件正文 | 1（最高） |
| Instructions 配置 | 项目 | 项目kilo.jsonc中的instructions键 | 2 |
| AGENTS.md | 项目 | 项目根目录的AGENTS.md | 3 |
| Instructions 配置 | 全局 | 全局kilo.jsonc中的instructions键 | 4 |
| Skills | 两者 | .kilo/skills/、配置skills键 | 按需加载 |
上层来源的指令可以覆盖下层来源中的冲突内容；项目级指令先于全局指令加载，并对每个会话生效。
VSCode 中的指令配置
按 Agent 提示词（Per-Agent Prompts）
每个 Agent 都可以拥有独立的自定义提示词，通过设置界面配置：
- 打开Settings → Agent Behaviour → Agents子页签；
- 选中要定制的 Agent；
- 在该 Agent 的
prompt字段下的 Markdown 文本区输入指令； - 保存更改。
这些提示词会被注入到对应 Agent 的系统提示词（system prompt）中，作用于所有使用该 Agent 的会话。配置解析对应的实现位于 agent 配置插件，它会把配置中的system/prompt字段写入 Agent 定义。
指令文件（Instruction Files）
Kilo 会在项目根目录及其父目录中自动发现指令文件（基于findUp向上查找）。以下文件名会被识别：
AGENTS.md—— Kilo 的主指令文件；CLAUDE.md—— 为兼容性而支持；CONTEXT.md—— 额外的项目上下文。
将任意一个文件放在项目根目录，即可为整个项目提供指令。AGENTS.md本质上是为 AI 助手准备的"项目 README"，它随仓库版本管理、可跨多种 AI 编码工具复用（详见 agents.md 专题文档）。需要留意的是，AGENTS.md必须采用全大写文件名，且该文件受写保护——Agent 修改它需要显式的用户批准。
全局指令（Global Instructions）
当指令需要跨所有项目生效时，把AGENTS.md放到全局配置目录：
- Kilo：
~/.config/kilo/AGENTS.md； - Claude 兼容：
~/.claude/CLAUDE.md，直到执行过 Claude Code 迁移。迁移完成后该全局回退机制失效，但项目级的CLAUDE.md文件仍可正常工作。
项目级指令先于全局指令加载，并且适用于每一个会话。在源码中，全局指令的读取路径由 Global 服务 提供：config目录默认为~/.config/kilo（遵循 XDG 约定），并可通过KILO_CONFIG_DIR环境变量覆盖。
目录级指令（Per-Directory Instructions）
可以在项目的任意子目录放置AGENTS.md。这些文件是动态加载的——当 Agent 的 Read 工具访问该目录下的文件时，对应的AGENTS.md才会被发现，其内容以<system-reminder>标签的形式注入到会话上下文中。
这一机制非常适合 monorepo 或多模块项目：子目录的AGENTS.md无需重复根级指令，只需补充该目录任务范围内的特定约束即可（例如后端目录强调数据库规范、docs 目录强调文档写作规范）。
补充指令来源（Additional Instruction Sources）
kilo.jsonc中的instructions键接受一个指向额外指令文件的路径、glob 通配符或 URL 数组。这些条目可在Settings → Agent Behaviour → Rules子页签中管理：
# 指令来源示例 instructions: - ./docs/coding-standards.md - ./teams/frontend-rules.md - https://example.com/team-instructions.md关于 URL 型指令：URL 指令源在会话启动时抓取，超时时间为 5 秒。如果 URL 不可达，该指令源会被静默跳过，不会中断会话。
旧版.kilocoderules支持
如果项目里保留了 VSCode 扩展时代的.kilocoderules文件，它们仍会通过自动迁移（auto-migration）被加载。不过对新项目，官方推荐迁移到AGENTS.md。
CLI 中的指令配置
CLI 与 VSCode 的分层思路一致，但配置载体是文件：Agent 定义文件与kilo.jsonc。
按 Agent 提示词（Per-Agent Prompts）
每个 Agent 的自定义提示词可以写在.md文件中（作为 Markdown 正文），也可以通过kilo.jsonc的agent.<name>.prompt键指定：
// kilo.jsonc { "agent": { "code": { "prompt": "You are a Python specialist. Follow PEP8 strictly.", }, }, }或者以 Markdown 正文形式放在.kilo/agents/code.md：
--- description: Python specialist --- You are a Python specialist. Follow PEP8 strictly.两种方式注入的是同一个 Agent 系统提示词槽位，对所有使用该 Agent 的会话生效。从源码看，Agent 定义文件（位于agent/agents/**/*.md与mode/modes/*.md）会由 config-agent 插件 自动发现并解析：Markdown frontmatter 中的元数据字段（model、description、permissions 等）映射为 Agent 属性，正文则作为系统提示词内容。
指令文件（Instruction Files）
与 VSCode 相同，CLI 会在项目根目录及父目录自动发现以下文件（通过findUp）：
AGENTS.md—— 主指令文件；CLAUDE.md—— 兼容支持；CONTEXT.md—— 额外项目上下文。
全局指令（Global Instructions）
跨项目生效的全局AGENTS.md位置：
- Kilo：
~/.config/kilo/AGENTS.md； - Claude 兼容：
~/.claude/CLAUDE.md，直到执行过 Claude Code 迁移。
项目级指令先加载，全局指令后加载，且两者都适用于每个会话。
目录级指令（Per-Directory Instructions）
与 VSCode 行为完全一致：任意子目录放置AGENTS.md，当 Read 工具访问该目录文件时动态发现并注入<system-reminder>，用于为 monorepo 的不同部分提供上下文专属指导。
补充指令来源（Additional Instruction Sources）
CLI 中直接在kilo.jsonc配置instructions数组：
// kilo.jsonc { "instructions": [ "./docs/coding-standards.md", "./teams/frontend-rules.md", "https://example.com/team-instructions.md", ], }配置解析层对instructions的完整支持可由 config 测试 佐证——测试中验证了instructions数组同时接受普通路径（如CONTRIBUTING.md）、glob（如.cursor/rules/*.md）与 URL（如https://example.com/shared-rules.md）三种形式。
旧版.kilocoderules支持
CLI 同样兼容旧版.kilocoderules文件，通过自动迁移加载；新项目推荐迁移到AGENTS.md。
源码级原理：指令如何被发现、聚合与注入
InstructionContext 系统上下文
指令加载的核心实现位于 instruction-context.ts。它注册了一个名为core/instructions的 SystemContext，负责把项目与全局的指令文件聚合成一段可注入的文本。
核心逻辑在observe函数中（instruction-context.ts#L40-L74）：
- 以当前工作目录为起点、项目根目录为终点（
stop），调用fs.up({ targets: ["AGENTS.md"], start, stop })向上查找所有AGENTS.md； - 将全局配置目录下的
AGENTS.md（join(global.config, "AGENTS.md")）并入结果，并去重； - 并发读取这些文件的全部内容，组装为
File { path, content }列表； - 若某个被发现的文件在读取前消失，则整体视为
SystemContext.unavailable（避免注入不完整指令）。
查找边界受Location.Service控制：只有位于规范项目根目录内的目录才会触发项目指令查找，否则跳过（对应测试见 instruction-context.test.ts#L293-L322）。
向上查找（fs.up）的实现
fs.up定义在 fs-util.ts，签名如下：
readonly up: (options: { targets: string[]; start: string; stop?: string }) => Effect.Effect<string[], Error>它从start开始逐级向上，在每个目录层级依次匹配targets中的文件名（当前核心实现的目标数组为["AGENTS.md"]），直到stop为止，返回所有命中文件的路径。
聚合渲染与动态更新
所有被发现的文件通过render函数合并为一段文本（instruction-context.ts#L99-L101）：
Instructions from: <文件路径> <文件内容>文件之间以空行分隔。由于该系统上下文是可观测的，当某个AGENTS.md在会话中途被修改或删除时，上下文会动态更新：
- 内容变化时，更新文本为
These instructions replace all previously loaded ambient instructions.并携带新内容； - 全部文件被删除时，更新文本为
Previously loaded instructions no longer apply.
这一行为由 instruction-context.test.ts#L32-L110 的实时测试完整验证：测试创建全局、项目、子包三层AGENTS.md，断言聚合基线顺序为 全局 → 子包 → 项目，并验证修改、删除文件后上下文的增量更新。
环境变量控制
KILO_DISABLE_PROJECT_CONFIG：置为非空值可整体关闭项目级指令发现（flag.ts#L131-L134），对应测试见 instruction-context.test.ts#L258-L291。注意它只禁用项目指令的向上扫描，不会影响全局AGENTS.md；KILO_CONFIG_DIR：覆盖全局配置目录位置（flag.ts#L140-L142），可用于将全局AGENTS.md指向自定义路径。
与其他指令源的协作
AGENTS.md并非唯一的指令来源。instructions配置（项目级与全局级）、Agent 提示词以及 Skills 会在会话组装时一同参与系统提示词的构建。instructions数组中的条目按配置顺序加载，glob 匹配到的文件按文件系统顺序加载；项目级指令在冲突时优先于全局指令。若项目中仍存在旧版.kilocode/rules/目录，其内容也会为向后兼容而自动包含（详见 Custom Rules 文档）。
实战建议
- 用
AGENTS.md承载"会随仓库走"的规则：放入代码风格、架构约束、测试与安全要求，随版本库提交，保证团队成员与 CI 场景下的行为一致； - 用
instructions键承载"本地化"的规则：如团队内部文档、临时约束，需要时用 JSONC 的//注释即可暂时禁用某个条目； - 用全局
~/.config/kilo/AGENTS.md承载个人偏好：例如个人偏好的格式化风格、默认语言习惯，这些不该进入团队仓库； - 用目录级
AGENTS.md治理 monorepo：让每个模块的规则就近维护，避免根级文件无限膨胀； - 指令应具体、可验证：如"限制圈复杂度小于 10"优于"写出好代码"，并配合代码示例说明期望模式。
相关功能
- Custom Modes（自定义模式）
- Custom Rules（自定义规则）
- Settings 管理
- Auto-Approval 设置
- 人工智能
- 大模型
- AI Agent
- 代码智能体
- 工具调用
- 交互助手
- CLI
【免费下载链接】kilocode
Kilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.
相关推荐
VS Code 自定义指令（Custom Instructions）完全指南：为 AI 编码助手配置项目级与文件级规则
VS Code 自定义指令（Custom Instructions）完全指南：为 AI 编码助手配置项目级与文件级规则 自定义指令（Custom Instruc
文档教程Zed Agent Instructions 机制详解：AGENTS.md 与项目指令文件的配置、优先级与底层加载原理
Zed Agent Instructions 机制详解：AGENTS.md 与项目指令文件的配置、优先级与底层加载原理 本文基于 Zed 官方文档 instru
开发工具代码编辑器桌面应用Kilo Code 自定义子代理（Custom Subagents）完全指南：从配置、权限到源码级实现
Kilo Code 自定义子代理（Custom Subagents）完全指南：从配置、权限到源码级实现 导读 Kilo Code 的 CLI 与 VS Code
人工智能大模型AI Agent代码智能体工具调用交互助手CLI
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
