Improving Rules

Once a rule exists, you can improve it: narrowing false positives, broadening coverage, or adjusting severity. This works for a rule in any engine, not only ast-grep rules: a Vale rule that fires too eagerly is improved the same way an sg rule is.

When to Improve a Rule

• False positives: the rule matches code that is correct
• Missing edge cases: the rule doesn’t catch a pattern it should
• Scope changes: you want to broaden or narrow what the rule targets
• Better messaging: the rule’s message or note could be clearer

Running It

Ask your coding agent, and it fetches the recipe:

npx @taskless/cli agent improve-rule

The command that recipe runs is available directly too:

npx @taskless/cli rule improve --from <file>

The --from flag points to a JSON file containing your improvement request. The CLI regenerates the rule and updates the files in that rule’s directory under .taskless/rules/<engine>/<id>/, tests included.

JSON Input Format

The improvement request is a JSON file with the following fields:

Field	Type	Required	Description
ruleId	string	Yes	The ticket ID of the rule to improve, see the note below
guidance	string	Yes	Natural language description of the improvements to make
references	array	No	File content to attach as context for better accuracy

Each entry in references is an object with:

Field	Type	Description
filename	string	Path identifying the example file
content	string	The file content

ruleId is not the rule’s file name

It is the ticket ID reported as ruleId by npx @taskless/cli rule create --json when the rule was created. It cannot be read back from anything under .taskless/, so if you did not keep it, you cannot reconstruct it from the rule directory.

The CLI documents this field two ways

The rule improve input schema describes filename as a path relative to .taskless/, while the recipe’s own step 5 treats references as code examples gathered from your repository. Those cannot both be routine. Use a path that identifies the example to a human reader; the field is context for the request, not something the CLI resolves on disk.

Example

{
  "ruleId": "no-triple-slash-reference",
  "guidance": "Also flag /// <reference lib=... /> directives, not just types and path",
  "references": [
    {
      "filename": "src/worker.ts",
      "content": "/// <reference lib=\"es2015\" />\nimport { Hono } from 'hono';"
    }
  ]
}

How Agents Use This

AI coding agents (like Claude Code with Taskless skills installed) use this command to iterate on rules automatically. The typical agentic workflow is:

1. The agent identifies a rule that needs improvement (e.g., from a false positive during taskless check)
2. The agent writes the JSON request file to .taskless/.tmp-iterate-request.json
3. The agent runs taskless rule improve --from .taskless/.tmp-iterate-request.json
4. Taskless regenerates the rule and updates the files in your repository
5. The agent re-runs taskless verify and taskless test on the rule directory to confirm the change holds

Without an Account

If you’re not authenticated, your coding agent can still improve rules locally. The agent reads the existing rule, analyzes your codebase for context, and iterates on the rule directly, with no API calls needed. Ask your agent to “improve this taskless rule” and it will use whichever path is available.