Skip to content

feat(rules): add built-in token-efficiency rule - #239

Closed
jeff-r2026 wants to merge 1 commit into
mainfrom
worktree-builtin-token-efficiency-rule
Closed

feat(rules): add built-in token-efficiency rule#239
jeff-r2026 wants to merge 1 commit into
mainfrom
worktree-builtin-token-efficiency-rule

Conversation

@jeff-r2026

Copy link
Copy Markdown
Collaborator

What

Adds a CLI built-in rule token-efficiency.md, deployed by teamai pull to every installed tool's rules directory via the existing builtin-rules mechanism (same path as teamai-recall).

It distills our internal Effective Token 使用规范 into the subset of clauses that actually change agent behavior at the system-prompt layer:

  • Grounding over memory — check files/symbols/git via tools instead of guessing (anti-hallucination → fewer retries)
  • Search before you readgrep/glob to locate, then bounded-range reads; narrow command output at the source
  • Tools/scripts over model reasoning — mechanical work goes to linters/sed/CLIs, not step-by-step reasoning
  • Minimal, focused output — no filler, show diffs not whole files
  • Persist durable info to files, and YAGNI before writing new code

Human-only guideline actions (session isolation, /compact, /clear) are intentionally excluded — they can't be enforced through a system-prompt rule.

Design notes

  • Unlike teamai-recall, token-efficiency is always deployed (not gated by the recall toggle) — it's a general guardrail.
  • Auto-excluded from teamai push via EXCLUDED_RULE_NAMES and cleaned up on uninstall via BUILTIN_RULE_NAMES — no separate wiring needed.
  • Docs updated in both docs/usage-guide.md and docs/usage-guide.zh-CN.md (new "Built-in rules" table).

Test Plan

  • npx tsc --noEmit — no errors
  • npx vitest run — 1767 passed, 0 failed (added 3 cases in builtin-rules.test.ts)
  • npm run build — build success
  • Real E2E: invoked deployBuiltinRules against a throwaway HOME; confirmed token-efficiency.md (53 lines) lands in .claude/rules/ alongside teamai-recall.md, and is still deployed when skipRecall: true

🤖 Generated with Claude Code

Distill the team's "Effective Token" guidelines into an AI-actionable
built-in rule, deployed by `teamai pull` alongside teamai-recall via the
existing builtin-rules mechanism.

The rule covers the guideline clauses that actually change agent behavior:
grounding over memory (anti-hallucination), search before full-file reads
with bounded ranges, tools/scripts over model reasoning, minimal output,
persisting durable info to files, and YAGNI. Human-only actions from the
guidelines (session isolation, /compact, /clear) are intentionally left out
since they can't be enforced via a system-prompt rule.

Unlike teamai-recall, token-efficiency is always deployed and not gated by
the recall toggle. It is excluded from `teamai push` (EXCLUDED_RULE_NAMES)
and cleaned up on uninstall (BUILTIN_RULE_NAMES), both automatically.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@jeff-r2026 jeff-r2026 closed this Jul 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant