agentleFS
tbhbtbhb/vale-ai-tells/CLAUDE.md

vale-ai-tells

CLAUDE.md118 starsChanged 37 days agoMITView on GitHub

Refer to @AGENTS.md for commit conventions and the prose-lint output contract. What follows is specific to this repository. vale-ai-tells provides a Vale package for detecting linguistic patterns commonly associated with AI-generated prose. It provides YAML rule files that flag vocabulary fingerprints, structural patterns, and rhetorical tells. The README tracks the current rule count. First-time setup: A clone already contains the vendored payload, because it is committed. Delete it and every mise command that reads tasks fails while loading the configuration,…

The file

We split this CLAUDE.md into the rules it gives an agent

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Add or update the rule's cases in tests/<style>/<Rule>.test.yml, one per token family and one per guard, and run mise run test

    line 121
  2. Distinctive:

    Ensure rules don't have excessive false positives

    line 122
  3. Distinctive:

    Update README.md if adding/removing rules

    line 123

≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

Claude Code instructions

Refer to @AGENTS.md for commit conventions and the prose-lint output contract. What follows is specific to this repository.

Project overview

vale-ai-tells provides a Vale package for detecting linguistic patterns commonly associated with AI-generated prose. It provides YAML rule files that flag vocabulary fingerprints, structural patterns, and rhetorical tells. The README tracks the current rule count.

Repository structure

vale-ai-tells/
├── styles/
│   ├── ai-tells/               # Core prose rules (*.yml)
│   ├── ai-tells-commits/       # Commit-message rules (*.yml)
│   ├── ai-tells-experimental/  # Opt-in structural and metric rules (*.yml)
│   └── config/                 # Tengo scripts, the agent template, vocabularies
├── tests/                      # Per-rule vale test cases (<style>/<Rule>.test.yml)
├── .github/workflows/          # CI, security, release, and Renovate automation
├── .config/mise/conf.d/        # Vendored devtools tool pins (vendir owns this)
├── .devtools/tasks/             # Vendored devtools shared tasks (vendir owns this)
├── .pre-commit-config.yaml
├── .vale.ini                   # Repo dev config (enables all three styles)
├── mise.toml                   # Repo-specific pins and tasks; selects the shared ones
├── mise.lock                   # Resolved versions, URLs, and digests
├── vendir.yml                  # The devtools payload: source, tag, target directories
├── vendir.lock.yml             # The commit each directory resolved to
├── README.md
├── AGENTS.md                   # Commit and prose-output contract for agents
├── EXPERIMENTAL.md             # Experimental-rule reference
├── CHANGELOG.md
├── TODO.md
├── test-document.md            # Positive fixtures (patterns should fire)
├── test-false-positives.md     # Negative fixtures (should stay clean)
└── test-commit-messages.md     # Commit-message fixtures

Development workflow

First-time setup:

mise run bootstrap   # vendir sync, mise install, vale sync, prek install

A clone already contains the vendored payload, because it is committed. Delete it and every mise command that reads tasks fails while loading the configuration, because the stamps in mise.toml extend templates only the payload defines. That is the enforcement, not a bug. mise install and vendir sync keep working through it, which is what recovers the tree.

Testing rules locally:

vale --config=.vale.ini test-document.md
mise run test-rules   # the per-rule cases under tests/
mise run test         # the rule cases, then the false-positive fixtures stay clean

Cases for a rule go in tests/<style>/<Rule>.test.yml, with rule: ../../styles/<style>/<Rule>.yml isolating it. Assert with contains (the check name and the quoted match) and absent. Keep them out of styles/: vale before 3.24 loads every .yml there as a rule, and a test file breaks vale sync for consumers.

Measuring a candidate token:

mise run corpus-build                          # once per machine, into ~/.cache/vale-ai-tells/corpus
mise run corpus-grep 'rather than [a-z]+ing'   # count a PCRE pattern per corpus, with sample paragraphs

A token is counted against human technical prose written before the models before it is added to a rule, and the count goes in the rule comment with an example hit or two. The Go and Python standard library corpora are reference prose, and the PEPs, Go proposals, Go blog, Rust RFCs, and Pro Git are explanation and argument, so quote the argumentative ones for a clause-level construction. A count in the tens that is the construction itself stays and gets documented, while one in the hundreds is ordinary English and measures out. Confirm the settled count through Vale over the corpus files, since Vale uses a different regex engine than the grep task. The header of tools/corpus-build.sh lists the sources and pins.

Running the gates:

Gates from the vendored payload use a devtools: prefix. The rest belong to this repository.

mise run lint                        # every linter below, in one pass
mise run devtools:check-vendored    # the vendored payload matches what git holds
mise run devtools:check-pins        # every tbhb-dev/devtools pin site names one release
mise run devtools:lint-yaml         # ryl
mise run devtools:lint-markdown     # rumdl
mise run devtools:lint-config       # biome on JSON
mise run devtools:lint-spelling     # cspell
mise run lint-prose                  # Vale on the docs
mise run lint-messages               # Vale on each rule's own message: field (dogfooding)
mise run devtools:lint-toml         # tombi
mise run devtools:lint-mise         # mise fmt --check
mise run lint-editorconfig
mise run devtools:lint-workflows    # actionlint
mise run check-all                   # lint, test, and the full-history gitleaks scan

Pre-commit hooks:

mise run devtools:prek          # run hooks on staged files
mise run devtools:prek-all      # run hooks on all files

Building and releasing:

mise run build-package # write the three release zips locally
mise run release vX.Y.Z

Rule conventions

All rules use error level by default. Users can override this in their .vale.ini. Core rules use Vale's existence and sequence extensions, plus occurrence for the density rule and substitution for the house-compound swaps. The experimental style adds script (Tengo), metric, capitalization, and substitution rules. Each rule needs:

  • message: Clear explanation of why the rule flags the pattern
  • level: Always error
  • tokens or swap: The patterns to match
  • A comment recording what the tokens cost on the pre-LLM corpora and what was measured out, from the corpus tasks above

Messages must pass the ai-tells style themselves. Avoid em-dashes and anthropomorphic or cliché idioms. Give the good word rather than quoting the flagged one. Write each message as AI <label>: '%s'. <concrete action>. so agents can act on it. mise run lint-messages enforces this: tools/lint-messages.sh copies each message field into a scratch Markdown file and lints it as prose. It runs as part of mise run lint.

Tone

Appreciate the irony: an AI working on a tool that detects AI writing. Lean into it. Find the humor in flagging your own tendencies and catching yourself mid-cliché while helping humans spot the patterns you statistically tend to produce.

Quality standards

Before committing changes:

  1. Add or update the rule's cases in tests/<style>/<Rule>.test.yml, one per token family and one per guard, and run mise run test
  2. Ensure rules don't have excessive false positives
  3. Update README.md if adding/removing rules

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.