alunduil / alunduil/zfs-replicate
Vale holds AI-targeted instruction files to a concision bar
- 主要言語
- Python
- スター
- 24
- フォーク
- 6
- 平均マージ
- 3時間 11分
- マージ済み PR(30日)
- 49
説明
## Summary
Vale lints `CLAUDE.md` with the human documentation styles and reports 42 findings, none of which anyone has acted on. Those rules are the right bar for an instruction file: short sentences, few semicolons, active voice, plain words. Add the one check they lack, stop the one that mislabels the subject matter, and rewrite `CLAUDE.md` until it passes.
## Motivation
`CLAUDE.md` is loaded into an agent's context every session, so density and clarity have a direct cost. Concision rules serve that goal rather than fighting it. The file currently accumulates the findings instead of clearing them, and resolving #427 (via #472) worked around the linter rather than with it.
This issue originally proposed excluding these files from Vale. Review on #512 set the opposite direction: keep the files linted, and make the linting useful.
## Scope
**Add a sentence-length rule scoped to instruction files.** The packaged `SentenceLength` rules count words; instruction prose packs clauses, so a character cap catches what they miss. `extends: occurrence` with `scope: sentence`, `token: .`, and a character `max` gives that. Enable it by rule name in a per-pattern `.vale.ini` section so the file keeps every existing style:
```ini
[{CLAUDE,AGENTS}.md]
Agent.SentenceLength = YES
[.claude/**/*.md]
Agent.SentenceLength = YES
```
**Add `agent` and `agents` to `styles/config/vocabularies/ZFS/accept.txt`.** `Microsoft.Terms` asks three times for "personal digital assistant" instead of "agent" in a file whose subject is agents. The vocabulary suppresses it everywhere, which is correct: the word is legitimate throughout this repo, not just in instruction files.
**Rewrite `CLAUDE.md` against the resulting rule set.** Roughly 38 findings remain after the two config changes, and each one names real work: twelve semicolon reports across `Google.Semicolons` and `Microsoft.Semicolon`, twelve passive-voice reports, four sentence-length reports, plus `Microsoft.Wordiness`, `write-good.TooWordy`, `write-good.Weasel`, `RedHat.SimpleWords`, `Google.Will`, and `RedHat.Headings`.
Vale runs only through pre-commit here, so no CI workflow change is needed.
## Out of scope
`alex.ProfanityUnlikely` fires on ordinary technical words across the whole repo, not only instruction files: `destroy` and `failed` in `docs/adr/0001`, `execution` in `docs/reference/testing.md`, `period` in `CONTRIBUTING.md`. Four of `CLAUDE.md`'s findings come from it. #664 covers that as part of consolidating the style packs.
## Acceptance criteria
- [ ] `pre-commit run vale --files CLAUDE.md` reports no findings apart from `alex.Profanity*`.
- [ ] The sentence-length rule also applies to `AGENTS.md` and to files under `.claude/`.
- [ ] `pre-commit run vale --files README.md` output matches current HEAD.
## Additional context
Direction set in ; #512 is the in-flight attempt and already carries the scoped rule. Overlaps #477 (CLAUDE.md best-practices audit), whose remaining scope is the best-practices review and length reduction. #664 consolidates the six style packs into one project style, which is where this issue's `SentenceLength` rule should eventually live.
コントリビューションガイド
調査の方向性
Review the existing Vale configuration, styles/config/vocabularies/ZFS/accept.txt, and CLAUDE.md, then inspect the scoped-rule work already carried in #512. Run pre-commit run vale --files CLAUDE.md and README.md to establish the current findings. Done means CLAUDE.md is clean except for alex.Profanity*, the rule covers AGENTS.md and .claude/, and README.md output is unchanged.
索引モデルが issue の本文から書いたものです。
評価
- 技術スタック
- markdown
- 領域
- documentation, tooling
- issue の種類
- ドキュメント
- 難易度
- 4/5
- 見積もり時間
- 3〜5日
- 活発さ
- 停滞
- 明瞭さ
- 明確に書かれている
- 初心者へのやさしさ
- 35/100