AI Assistant (Claude) Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
The AI Assistant (Claude) Guidelines define the operational framework for Claude Code, an interactive software-engineering agent, within the numan-plugins repository. These guidelines ensure that the assistant adheres to project-specific tool selection, development workflows, and security protocols designed to maintain the integrity of the plugin build and delivery pipeline.
The primary purpose of these guidelines is to govern how the assistant interacts with the codebase, particularly through the use of the Serena MCP server for symbolic code analysis and editing. These rules supersede default tool descriptions to prevent incorrect behaviors, such as premature abstractions or improper tool usage on code files.
Tool Selection and Usage
The project utilizes the Serena MCP server, which provides semantic, symbol-aware tools for reading and editing code. The assistant is required to treat Serena tools as the primary method for code interaction.
Tool Mapping Matrix
| Task | Preferred Serena Tool |
|---|---|
| View code structure | get_symbols_overview |
| Read specific symbol | find_symbol (include_body=true) |
| Find symbol across repo | find_symbol |
| Find references/callers | find_referencing_symbols |
| Edit symbol body | replace_symbol_body |
| Insert near symbol | insert_before_symbol / insert_after_symbol |
| Rename/move/delete | rename / _move / _safe_delete |
Sources: CLAUDE.md:6-33
Usage Exceptions
Built-in Read, Edit, Glob, and Grep tools are permitted only under specific conditions:
- Serena has failed on the target file.
- The file is not parseable as code (e.g., JSON, YAML, Markdown).
- A regex search across many files is required for discovery.
- Only a few lines need to be read, making symbolic tools inefficient.
Sources: CLAUDE.md:35-46
Required Engineering Workflow
Before modifying any code, the assistant must follow a strict sequence of actions to ensure precision and minimize side effects.
The workflow ensures that the assistant builds a precise mental model of the code before making the smallest possible change to satisfy the request.
Sources: CLAUDE.md:48-57
Development Defaults
- Minimal Changes: Avoid adding scope, abstractions for hypothetical needs, or unnecessary error handling.
- Comment Policy: Only write comments when the "WHY" is non-obvious (e.g., hidden constraints or workarounds).
- File Management: Prefer editing existing files over creating new ones.
- UI Changes: Explicitly state if UI changes cannot be tested in the current environment.
Sources: CLAUDE.md:63-76
Security and Safety Protocol
Safety is paramount, especially concerning the project's trust boundary and automated publication pipeline. The assistant must monitor for security vulnerabilities such as injection, secret leaks, and path traversal.
Action Authorization Levels
| Action Type | Examples | Requirement |
|---|---|---|
| Local/Reversible | Editing files, running tests, reading state | Free to take |
| Destructive | rm -rf, deleting branches, git reset --hard | Pause and confirm |
| Hard-to-reverse | Modifying CI/CD, removing dependencies | Pause and confirm |
| Externally Visible | Pushing, opening PRs, posting to 3rd party | Pause and confirm |
Sources: CLAUDE.md:80-97
Trust Boundary Invariants
The assistant must never violate the following architectural constraints:
- No Private Keys: Never add signing keys, PEM material, or registry secrets.
- Builds Only: This repo only builds and hosts binaries; signing occurs in
numan-registry. - Immutable Tags: Release tags and assets are immutable; existing assets must never be overwritten.
Sources: REVIEW.md:21-36, README.md:25-33
Git and Repository Management
The assistant operates under specific Git restrictions to maintain a clean and traceable history.
- Commits: Only commit when explicitly asked by the user.
- Staging: Stage files by name;
git add .orgit add -Ais prohibited to prevent accidental inclusion of secrets. - Commit Messages: Use HEREDOC for formatting and include the required trailer:
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>. - Hooks: Never use
--no-verifyor--forceto bypass validation scripts likevalidate_manifest.pyortest_workflow_safety.py.
Sources: CLAUDE.md:105-125, scripts/validate_manifest.py:126-141, scripts/test_workflow_safety.py:46-52
Output and Tone Guidelines
Claude's communication style is designed to be brief and professional, prioritizing tool actions over narration.
- Interaction: State the intent in one sentence before tool calls. Provide short updates at key findings or direction changes.
- Formatting: Use GitHub-flavored markdown and reference code as
path:line. - Summary: End every turn with a maximum of two sentences summarizing what changed and what is next.
- Deliberation: Do not narrate internal thinking or deliberation.
Sources: CLAUDE.md:131-147
The AI Assistant (Claude) Guidelines facilitate a high-integrity development environment by enforcing precise tool usage, rigorous safety checks, and professional communication standards within the numan-plugins project.