feat: three-tier rules system

CHANGELOG.md

@@ -25,6 +25,8 @@ Only write entries that are worth mentioning to users.
 - Todo: Refactor SetTodoList to persist state and prevent tool call storms — todos are now persisted to session state (root agent) and independent state files (sub-agents); adds query mode (omit `todos` to read current state) and clear mode (pass `[]`); includes anti-storm guidance in tool description to prevent repeated calls without progress (fixes #1710)
 - ReadFile: Add total line count to every read response and support negative `line_offset` for tail mode — the tool now reports `Total lines in file: N.` in its message so the model can plan subsequent reads; negative `line_offset` (e.g. `-100`) reads the last N lines using a sliding window, useful for viewing recent log output without shell commands; the absolute value is capped at 1000 (MAX_LINES)
 - Shell: Fix black background on inline code and code blocks in Markdown rendering — `NEUTRAL_MARKDOWN_THEME` now overrides all Rich default `markdown.*` styles to `"none"`, preventing Rich's built-in `"cyan on black"` from leaking through on non-black terminals
+- 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
 
 ## 1.30.0 (2026-04-02)
 

docs/en/reference/slash-commands.md

@@ -276,6 +276,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

@@ -18,6 +18,8 @@ This page documents the changes in each Kimi Code CLI release.
 - Todo: Refactor SetTodoList to persist state and prevent tool call storms — todos are now persisted to session state (root agent) and independent state files (sub-agents); adds query mode (omit `todos` to read current state) and clear mode (pass `[]`); includes anti-storm guidance in tool description to prevent repeated calls without progress (fixes #1710)
 - ReadFile: Add total line count to every read response and support negative `line_offset` for tail mode — the tool now reports `Total lines in file: N.` in its message so the model can plan subsequent reads; negative `line_offset` (e.g. `-100`) reads the last N lines using a sliding window, useful for viewing recent log output without shell commands; the absolute value is capped at 1000 (MAX_LINES)
 - Shell: Fix black background on inline code and code blocks in Markdown rendering — `NEUTRAL_MARKDOWN_THEME` now overrides all Rich default `markdown.*` styles to `"none"`, preventing Rich's built-in `"cyan on black"` from leaking through on non-black terminals
+- 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
 
 ## 1.30.0 (2026-04-02)
 

docs/zh/reference/slash-commands.md

@@ -276,6 +276,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

@@ -18,6 +18,8 @@
 - Todo：重构 `SetTodoList` 工具，支持状态持久化并防止工具调用风暴——待办事项现在会持久化到会话状态（主 Agent）和独立状态文件（子 Agent）；新增查询模式（省略 `todos` 参数可读取当前状态）和清空模式（传 `[]` 清空）；工具描述中增加了防风暴指导，防止在没有实际进展的情况下反复调用（修复 #1710）
 - ReadFile：每次读取返回文件总行数，并支持负数 `line_offset` 实现 tail 模式——工具现在会在消息中报告 `Total lines in file: N.`，方便模型规划后续读取；负数 `line_offset`（如 `-100`）通过滑动窗口读取文件末尾 N 行，适用于无需 Shell 命令即可查看最新日志输出的场景；绝对值上限为 1000（MAX_LINES）
 - Shell：修复 Markdown 渲染中行内代码和代码块出现黑色背景的问题——`NEUTRAL_MARKDOWN_THEME` 现在将所有 Rich 默认的 `markdown.*` 样式覆盖为 `"none"`，防止 Rich 内置的 `"cyan on black"` 在非黑色背景终端上泄露
+- 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]` 子命令；规则状态按项目持久化存储
 
 ## 1.30.0 (2026-04-02)
 

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