alunduil / alunduil/zfs-replicate

Vale holds AI-targeted instruction files to a concision bar

オープン
#476 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る
enhancement
主要言語
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

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。