zai-org / zai-org/feedback

[建议 / Feature] 支持类 .claude/rules/ 的渐进式披露规则目录(按文件路径/类型条件加载指令)

Open
#209 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

priority: P2
Dominant language
No language data
Stars
22
Forks
1
PR merge metrics
No merged PRs in 30d

Description

提交前确认 · Pre-submission checklist

  • 我已搜索过现有 issue,确认这不是重复提议 / I searched existing issues and confirmed this isn't a duplicate.
  • 我已阅读 CONTRIBUTING.md / I've read CONTRIBUTING.md.

问题类别:对话 / Agent 交互 · Agent chat / interaction
涉及框架:ZCode Agent(自研)
你认为的优先级:中 · Medium


使用场景 · Use case

在大型或多人协作项目中,随着架构规范、编码规范、各模块规则和踩坑记录不断累积,AGENTS.md 会持续膨胀。这些规则无论本次任务是否相关,每次会话都会全量注入——比如只做一个局部小改动时,与本次无关的其他模块规则照样占满上下文,既浪费 token,又稀释了真正相关规则的注意力。

目前 ZCode 现有的替代机制各有局限,难以补上这块能力:

  • Skills:主要靠用户手动 `$skill-name` 触发,自动触发可靠性不足以承载"规则"这种需要稳定、被动生效的指令;
  • Hooks:语义是为拦截工具调用设计的,不适合承载规则文本;
  • 手动拆分多个 AGENTS.md:受限于单文件全量注入,无法按上下文选择性加载。

因此目前缺少一种"只在特定上下文(如正在编辑某类文件、或处于某个子目录)时自动加载对应规则"的原生机制。Claude Code 对此有一套成熟的细粒度方案:`.claude/rules/*.md` 支持按子目录或文件类型条件加载,只有 Agent 编辑匹配文件时对应规则才被注入,不匹配则完全不加载。

建议方案 · Proposal

在 ZCode 中提供原生的"条件加载规则目录"机制,参考 Claude Code 的 `.claude/rules/` 模型,并与现有 AGENTS.md / Skills 体系互补:

  1. 规则目录约定:支持在工作区/用户级放置规则文件目录(如 `.zcode/rules/*.md`),每个文件由 frontmatter 声明触发条件
  2. 触发条件维度(建议至少支持其一):
    • 文件路径 glob(如 `src/web/**/*.ts`)
    • 文件类型/扩展名(如 `*.md`、配置类文件)
    • 子目录范围(编辑该目录下文件时才加载)
    • 关键词/任务语义(description 命中时加载,类似 Skills 的自动触发)
  3. 加载时机:Agent 即将读写匹配文件、或任务语义命中时,由 ZCode 自动将对应规则注入上下文;不命中则不注入。
  4. 与现有机制的关系AGENTS.md 承载"始终生效的全局规则";rules 目录承载"仅在特定上下文相关的规则";Skills 承载"可复用工作流"。三者形成清晰的渐进式披露分层。
  5. 迁移友好:复用 AGENTS.md 的分层合并语义(用户级 + 工作区级),并兼容从 Claude Code `.claude/rules/` 迁移。

预期价值 · Expected value

  • 显著降低 token 成本:规则按需加载,无关规则不再占用每会话上下文(大型项目收益尤其明显)。
  • 规则可无限扩展:解除"AGENTS.md 越大越重"的约束,团队可按子域无限细分规则而无需担心注入成本。
  • 生态对齐:`.claude/rules/` 已是事实标准并被广泛采用,ZCode 提供等价能力可降低跨工具迁移成本,吸引 Claude Code 用户。

补充材料 · Additional context

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the existing AGENTS.md and Skills documentation, then compare the proposed .zcode/rules/.md model with the referenced .claude/rules/.md behavior. The issue does not name implementation files or tests; define the supported condition syntax, rule-loading timing, and interaction with AGENTS.md and Skills before implementation. Done means matching rules are injected only for relevant files or tasks.

Written by the indexing model from the issue text.

Assessment

Domain
ai, developer-experience, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.