feat: three-tier rules system

CHANGELOG.md

@@ -11,6 +11,8 @@ Only write entries that are worth mentioning to users.
 
 ## Unreleased
 
+- Core: Add three-tier rules system for development guidelines — introduces builtin, user (`~/.config/agents/rules/`), and project (`.agents/rules/`) level rules with YAML frontmatter support (name, description, paths, priority, extends); active rules are automatically injected into the system prompt with size (32 KiB default) and count (10 default) limits; rules can be enabled/disabled per path pattern
+- Shell: Add `/rules` command to manage development rules — supports `list [level] [--all]`, `show <rule-id>`, `on/off <rule-id>`, and `reset [--hard]` subcommands; rules status is persisted per project
 - Shell: Use `git ls-files` for `@` file mention discovery — file completer now queries `git ls-files --recurse-submodules` with a 5-second timeout as the primary discovery mechanism, falling back to `os.walk` for non-git repositories; this fixes large repositories (e.g., apache/superset with 65k+ files) where the 1000-file limit caused late-alphabetical directories to be unreachable (fixes #1375)
 - Core: Add shared `file_filter` module — unifies file mention logic between shell and web UIs via `src/kimi_cli/utils/file_filter.py`, providing consistent path filtering, ignored directory exclusion, and git-aware file discovery
 - Shell: Prevent path traversal in file mention scope parameter — the `scope` parameter in file completer requests is now validated to prevent directory traversal attacks

docs/en/guides/interaction.md

@@ -19,7 +19,7 @@ $ git status
 $ npm run build
 ```
 
-Shell mode also supports some slash commands, including `/help`, `/exit`, `/version`, `/editor`, `/changelog`, `/feedback`, `/export`, `/import`, and `/task`.
+Shell mode also supports some slash commands, including `/help`, `/exit`, `/version`, `/editor`, `/changelog`, `/feedback`, `/export`, `/import`, `/rules`, and `/task`.
 
 ::: warning Note
 In shell mode, each command executes independently. Commands that change the environment like `cd` or `export` won't affect subsequent commands.

docs/en/reference/slash-commands.md

@@ -3,7 +3,7 @@
 Slash commands are built-in commands for Kimi Code CLI, used to control sessions, configuration, and debugging. Enter a command starting with `/` in the input box to trigger.
 
 ::: tip Shell mode
-Some slash commands are also available in shell mode, including `/help`, `/exit`, `/version`, `/editor`, `/theme`, `/changelog`, `/feedback`, `/export`, `/import`, and `/task`.
+Some slash commands are also available in shell mode, including `/help`, `/exit`, `/version`, `/editor`, `/theme`, `/changelog`, `/feedback`, `/export`, `/import`, `/rules`, and `/task`.
 :::
 
 ## Help and info
@@ -262,6 +262,22 @@ Usage:
 
 When plan mode is enabled, the prompt changes to `📋` and a blue `plan` badge appears in the status bar.
 
+### `/rules`
+
+Manage development rules. Rules are development guidelines and coding standards defined for projects, supported at three levels: builtin, user (`~/.config/agents/rules/`), and project (`.agents/rules/`). Active rules are automatically injected into the system prompt.
+
+Usage:
+
+- `/rules list [level] [--all]`: List all rules and their status
+  - `level`: Optional filter, specify `builtin`, `user`, or `project`
+  - `--all`: Also show disabled rules
+- `/rules show <rule-id>`: View the full content of a specified rule
+- `/rules on <rule-id>`: Enable a specified rule
+- `/rules off <rule-id>`: Disable a specified rule
+- `/rules reset [--hard]`: Reset rule status to defaults, `--hard` also deletes the state file
+
+Rule status is persisted per project in `.agents/rules.state.toml`.
+
 ### `/task`
 
 Open the interactive task browser to view, monitor, and manage background tasks.

docs/en/release-notes/changelog.md

@@ -4,6 +4,8 @@ This page documents the changes in each Kimi Code CLI release.
 
 ## Unreleased
 
+- Core: Add three-tier rules system for development guidelines — introduces builtin, user (`~/.config/agents/rules/`), and project (`.agents/rules/`) level rules with YAML frontmatter support (name, description, paths, priority, extends); active rules are automatically injected into the system prompt with size (32 KiB default) and count (10 default) limits; rules can be enabled/disabled per path pattern
+- Shell: Add `/rules` command to manage development rules — supports `list [level] [--all]`, `show <rule-id>`, `on/off <rule-id>`, and `reset [--hard]` subcommands; rules status is persisted per project
 - Shell: Use `git ls-files` for `@` file mention discovery — file completer now queries `git ls-files --recurse-submodules` with a 5-second timeout as the primary discovery mechanism, falling back to `os.walk` for non-git repositories; this fixes large repositories (e.g., apache/superset with 65k+ files) where the 1000-file limit caused late-alphabetical directories to be unreachable (fixes #1375)
 - Core: Add shared `file_filter` module — unifies file mention logic between shell and web UIs via `src/kimi_cli/utils/file_filter.py`, providing consistent path filtering, ignored directory exclusion, and git-aware file discovery
 - Shell: Prevent path traversal in file mention scope parameter — the `scope` parameter in file completer requests is now validated to prevent directory traversal attacks

docs/zh/guides/interaction.md

@@ -19,7 +19,7 @@ $ git status
 $ npm run build
 ```
 
-Shell 模式也支持部分斜杠命令，包括 `/help`、`/exit`、`/version`、`/editor`、`/changelog`、`/feedback`、`/export`、`/import` 和 `/task`。
+Shell 模式也支持部分斜杠命令，包括 `/help`、`/exit`、`/version`、`/editor`、`/changelog`、`/feedback`、`/export`、`/import`、`/rules` 和 `/task`。
 
 ::: warning 注意
 Shell 模式中每个命令独立执行，`cd`、`export` 等改变环境的命令不会影响后续命令。

docs/zh/reference/slash-commands.md

@@ -262,6 +262,22 @@ Flow Skill 也可以通过 `/skill:<name>` 调用，此时作为普通 Skill 加
 
 开启 Plan 模式后，提示符变为 `📋`，底部状态栏显示蓝色的 `plan` 标识。
 
+### `/rules`
+
+管理开发规则（Rules）。Rules 是为项目定义的开发指南和编码标准，支持三层：内置（builtin）、用户级（`~/.config/agents/rules/`）和项目级（`.agents/rules/`）。激活的规则会自动注入到系统提示词中。
+
+用法：
+
+- `/rules list [level] [--all]`：列出所有规则及其状态
+  - `level`：可选过滤器，指定 `builtin`、`user` 或 `project`
+  - `--all`：同时显示已禁用的规则
+- `/rules show <rule-id>`：查看指定规则的完整内容
+- `/rules on <rule-id>`：启用指定规则
+- `/rules off <rule-id>`：禁用指定规则
+- `/rules reset [--hard]`：重置规则状态为默认值，`--hard` 同时删除状态文件
+
+规则状态按项目持久化存储在 `.agents/rules.state.toml` 中。
+
 ### `/task`
 
 打开交互式任务浏览器，查看、监控和管理后台任务。

docs/zh/release-notes/changelog.md

@@ -4,6 +4,8 @@
 
 ## 未发布
 
+- Core：新增三层规则系统（Rules）用于开发指南和编码标准——支持内置（builtin）、用户级（`~/.config/agents/rules/`）和项目级（`.agents/rules/`）三层规则，规则文件使用带 YAML frontmatter（name、description、paths、priority、extends）的 Markdown 格式；激活的规则会自动注入到系统提示词中，受大小限制（默认 32 KiB）和数量限制（默认 10 条）约束；支持按文件路径模式自动启用规则
+- Shell：新增 `/rules` 命令用于管理开发规则——支持 `list [level] [--all]`、`show <rule-id>`、`on/off <rule-id>` 和 `reset [--hard]` 子命令；规则状态按项目持久化存储
 - Shell：使用 `git ls-files` 进行 `@` 文件引用发现——文件补全器现在优先使用 `git ls-files --recurse-submodules` 查询文件列表（5 秒超时），非 Git 仓库则回退到 `os.walk`；此修复解决了大型仓库（如包含 6.5 万+文件的 apache/superset）中 1000 文件限制导致字母顺序靠后的目录无法访问的问题（修复 #1375）
 - Core：新增共享的 `file_filter` 模块——通过 `src/kimi_cli/utils/file_filter.py` 统一 Shell 和 Web 的文件引用逻辑，提供一致的路径过滤、忽略目录排除和 Git 感知文件发现
 - Shell：防止文件引用 scope 参数的路径遍历——文件补全器请求中的 `scope` 参数现在会经过验证，防止目录遍历攻击

src/kimi_cli/agents/default/system.md

@@ -126,6 +126,16 @@ When working on files in subdirectories, always check whether those directories
 
 If you modified any files/styles/structures/configurations/workflows/... mentioned in `AGENTS.md` files, you MUST update the corresponding `AGENTS.md` files to keep them up-to-date.
 
+# Active Rules
+
+The following development rules are currently enabled. You MUST follow these standards when writing or modifying code. Use `/rules list` to see all available rules and `/rules on|off <rule-id>` to toggle them.
+
+{% if KIMI_ACTIVE_RULES %}
+${KIMI_ACTIVE_RULES}
+{% else %}
+_No rules are currently active. Add rules to `~/.config/agents/rules/` or `.agents/rules/` to enable development guidelines._
+{% endif %}
+
 # Skills
 
 Skills are reusable, composable capabilities that enhance your abilities. Each skill is a self-contained directory with a `SKILL.md` file that contains instructions, examples, and/or reference material.

src/kimi_cli/config.py

@@ -172,6 +172,34 @@ class MCPConfig(BaseModel):
     )
 
 
+class RulesConfig(BaseModel):
+    """Rules system configuration for development guidelines."""
+
+    enabled: bool = Field(
+        default=True,
+        description="Enable the rules system for development guidelines",
+    )
+    auto_enable_by_path: bool = Field(
+        default=True,
+        description="Automatically enable rules matching current project file paths",
+    )
+    max_active_rules: int = Field(
+        default=10,
+        ge=1,
+        le=50,
+        description="Maximum number of active rules to inject into system prompt",
+    )
+    max_total_size: int = Field(
+        default=32 * 1024,
+        ge=0,
+        description="Maximum total size of rules content in bytes (0 = unlimited)",
+    )
+    include_source: bool = Field(
+        default=False,
+        description="Include rule source (level/id) in system prompt output",
+    )
+
+
 class Config(BaseModel):
     """Main configuration structure."""
 
@@ -211,6 +239,9 @@ class Config(BaseModel):
     services: Services = Field(default_factory=Services, description="Services configuration")
     mcp: MCPConfig = Field(default_factory=MCPConfig, description="MCP configuration")
     hooks: list[HookDef] = Field(default_factory=list, description="Hook definitions")  # pyright: ignore[reportUnknownVariableType]
+    rules: RulesConfig = Field(
+        default_factory=RulesConfig, description="Rules system configuration"
+    )
     merge_all_available_skills: bool = Field(
         default=False,
         description=(

src/kimi_cli/rules/__init__.py

@@ -0,0 +1,32 @@
+"""Rules system for development guidelines and coding standards."""
+
+from __future__ import annotations
+
+from kimi_cli.rules.discovery import (
+    find_first_existing_dir,
+    get_builtin_rules_dir,
+    get_project_rules_dir_candidates,
+    get_user_rules_dir_candidates,
+    resolve_rules_roots,
+)
+from kimi_cli.rules.injector import RulesInjector, load_active_rules
+from kimi_cli.rules.models import Rule, RuleMetadata, RuleState
+from kimi_cli.rules.parser import parse_rule_file
+from kimi_cli.rules.registry import RulesRegistry
+from kimi_cli.rules.state import RulesStateManager
+
+__all__ = [
+    "get_builtin_rules_dir",
+    "get_user_rules_dir_candidates",
+    "get_project_rules_dir_candidates",
+    "resolve_rules_roots",
+    "find_first_existing_dir",
+    "Rule",
+    "RuleMetadata",
+    "RuleState",
+    "parse_rule_file",
+    "RulesRegistry",
+    "RulesInjector",
+    "load_active_rules",
+    "RulesStateManager",
+]

src/kimi_cli/rules/common/coding-style.md

@@ -0,0 +1,32 @@
+---
+name: "Coding Style"
+description: "General coding style guidelines for all languages"
+priority: 100
+---
+
+# Coding Style Guidelines
+
+## Code Organization
+
+- **Small, focused files**: Aim for 200-400 lines per file, maximum 800 lines
+- **Single responsibility**: Each file/module should have one clear purpose
+- **Meaningful names**: Use descriptive variable, function, and class names
+
+## Code Quality
+
+- **Functions should be small**: Ideally under 50 lines
+- **Avoid deep nesting**: Maximum 4 levels of indentation
+- **Fail fast**: Validate inputs and preconditions early
+- **No silent failures**: Always handle errors explicitly
+
+## Comments and Documentation
+
+- **Self-documenting code**: Prefer clear names over comments
+- **Why, not what**: Comments should explain intent, not mechanics
+- **Keep comments current**: Update or remove outdated comments
+
+## General Principles
+
+- **DRY (Don't Repeat Yourself)**: Extract common logic into reusable functions
+- **YAGNI (You Aren't Gonna Need It)**: Don't add functionality until necessary
+- **KISS (Keep It Simple, Stupid)**: Simple solutions are better than clever ones

src/kimi_cli/rules/common/testing.md

@@ -0,0 +1,38 @@
+---
+name: "Testing Standards"
+description: "Guidelines for writing effective tests"
+priority: 110
+---
+
+# Testing Standards
+
+## Test Coverage
+
+- **Test critical paths**: Focus on business logic and edge cases
+- **Aim for meaningful coverage**: Quality over quantity (80% is a good target)
+- **Test behavior, not implementation**: Tests should verify what code does, not how
+
+## Test Structure
+
+- **Arrange-Act-Assert**: Structure tests clearly
+  - Arrange: Set up test data and conditions
+  - Act: Execute the code being tested
+  - Assert: Verify the expected outcome
+
+## Test Naming
+
+- **Descriptive names**: Test names should explain the scenario being tested
+- **Pattern**: `test_<function>_<condition>_<expected_result>`
+- **Example**: `test_calculate_discount_negative_price_raises_error`
+
+## Test Independence
+
+- **Isolated tests**: Each test should be independent and not rely on others
+- **Clean state**: Tests should clean up after themselves or use fresh fixtures
+- **Deterministic**: Tests should produce the same result every time
+
+## Test Maintenance
+
+- **Keep tests simple**: Test code should be simpler than production code
+- **Refactor tests**: Don't be afraid to improve test code structure
+- **Review test failures**: Never ignore failing tests