custom-linter-creator

Custom Linter Creator

Leverage the existing linter ecosystem of each language,lints/ Create custom lint rules in the directory. Design error messages as correction instruction prompts for AI agents.

Basic Concepts

• Leveraging Existing Ecosystems: Rather than building from scratch, add custom rules to the standard linter of each language
• AI-oriented Error Messages: Write lint violation messages as correction instructions that AI can understand and execute
• lints/ directory: project root's lints/ Place custom rules in

Language-specific Guides (Quick Links)

For detailed implementation steps, refer to references/language-ecosystems.md .

Language	Linter tool	Details Link
Rust	dylint	Rust (dylint)
TypeScript/JavaScript	ESLint	ESLint
Python	pylint	Python (pylint)
Go	golangci-lint	Go (golangci-lint)

Workflow

1. Identifying the Target Language

Check the project's language and select the appropriate linter from the table above.

Checklist:

• Identified the project's main language
• Confirmed that the corresponding linter tool can be installed

2. lints/ Directory Initialization

Following the language-specific guide, initialize thelints/ directory.

Checklist:

• lints/ Created the directory
• Placed language-specific configuration files (Cargo.toml / package.json, etc.)
• Created the entry point file

Verification: ls -la lints/ Check the file structure with .

3. Implementing Custom Rules

AI-oriented Error Message TemplateFollowing this, implement the rules.

Checklist:

• Created the rule file
• Wrote the error message as an AI-oriented correction instruction
• Included the template's 5 elements (violation content, correction steps, context, scope restrictions, reason)

Verification: Confirm that there are no syntax errors in the rule file.

4. Integrating into the Linter Configuration

Add the custom rules to the project's linter configuration.

Checklist:

• Registered the custom rules in the project's configuration file
• Set the rule severity (error/warning)

Verification: Confirm that there are no linter configuration loading errors.

5. Operation Check

Run → Verify → Fix Loop:

1. Run: Intentionally write violating code and run the linter
2. Verify: Check whether the AI-oriented error message is output correctly
3. Fix: If the message is unclear, fix it and run again

Execution commands by language:

Language	Execution command	Expected output
Rust	cargo dylint --all	File path and line number of the violation, and message for AI
TypeScript/JS	npx eslint .	Message corresponding to the violation location and messageId
Python	pylint --load-plugins=lints.checkers.xxx src/	Message code (e.g., C9001) and detailed message
Go	./bin/linter ./... or golangci-lint run	Location information of the violation and message

Check items:

• An error was detected by the violation code
• The error message contains 5 elements (violation content, fix procedure, context, scope, reason)
• After fixing, the error was resolved

AI-oriented error message template

All custom rules shall write error messages according to the following template.

Template structure

[違反内容]: 何が違反しているかを1文で説明
修正手順:
1. [具体的なアクション1]
2. [具体的なアクション2]
3. [具体的なアクション3]
コンテキスト: {file_path}:{line_number} の {identifier}
スコープ: 修正対象以外のコードは変更しないこと
理由: このルールが存在する理由を簡潔に記載

Note: {identifier} Replace with an identifier name according to the rule (module name, class name, function name, etc.).

Concrete example

Rust (mod.rs prohibition rule):

このファイルは mod.rs を使用しているが、プロジェクト規約で禁止されている。
修正手順:
1. このファイルの内容を親ディレクトリ名.rs にコピーする
2. 例: src/actors/mod.rs → src/actors.rs に移動する
3. mod.rs ファイルを削除する
4. 他ファイルの use/mod 宣言に変更は不要（パスは同じ）
コンテキスト: {file_path}:{line_number} の {module_name}
スコープ: 対象ファイルとその移動先のみ変更すること
理由: Rust 2018 エディションのモジュールスタイルに統一するため

ESLint (ambiguous suffix prohibition rule):

クラス '{class_name}' は曖昧なサフィックス '{suffix}' を使用している。
修正手順:
1. このクラスの責務を特定する（データアクセス？認証？調整？）
2. 責務を具体的に表す名前に変更する
   例: UserManager → UserRepository / UserAuthenticator / UserCoordinator
3. このクラスへの全参照を新しい名前に更新する
コンテキスト: {file_path}:{line_number} の {class_name}
スコープ: クラス定義とその参照のみ変更すること
理由: Managerは責務が曖昧で、コードの意図が伝わりにくいため

Design guidelines

1. Concrete fix procedure: Instead of "please fix", say "convert to snake_case and update all references"
2. With step numbers: If there are multiple steps, indicate the order with numbers
3. Context information: Include the file path, symbol name, and line number of the violation
4. Scope restriction: Clearly state that "code other than the fix target shall not be changed"
5. Explanation of the reason: Briefly state why this rule exists