mirror of
https://github.com/sigp/lighthouse.git
synced 2026-07-04 21:34:36 +00:00
Add AI assistant documentation and commands (#8785)
* Add AI assistant documentation and commands Adds structured documentation for AI coding assistants: - CLAUDE.md / AGENTS.md: Lightweight entry points with critical rules - .ai/: Shared knowledge base (CODE_REVIEW.md, DEVELOPMENT.md, ISSUES.md) - .claude/commands/: Claude Code skills for review, issue, release - .github/copilot-instructions.md: GitHub Copilot instructions Supports Claude Code, OpenAI Codex, and GitHub Copilot with modular, pointer-based structure for maintainability. Includes guidelines for AI assistants to prompt developers about updating these docs after receiving feedback, creating a continuous improvement loop. * Add parallel development tip with git worktrees * Address review feedback - Add missing details to DEVELOPMENT.md: fork-specific testing, database backends, cross-compilation targets, make test-release - Simplify AGENTS.md to pointer to CLAUDE.md (Codex can read files) * Address review feedback - Add priority signaling: Critical vs Important vs Good Practices - Restore actionable file references (canonical_head.rs, test_utils.rs, etc.) - Add Rayon CPU oversubscription context - Add tracing span guidelines - Simplify AGENTS.md to pointer * Address review feedback and remove Copilot instructions - Restore anti-patterns section (over-engineering, unnecessary complexity) - Restore design principles (simplicity first, high cohesion) - Add architecture guidance (dependency bloat, schema migrations, backwards compat) - Improve natural language guidance for AI comments - Add try_read lock pattern - Remove copilot-instructions.md (can't follow file refs, untestable)
This commit is contained in:
130
.ai/ISSUES.md
Normal file
130
.ai/ISSUES.md
Normal file
@@ -0,0 +1,130 @@
|
||||
# GitHub Issue & PR Guidelines
|
||||
|
||||
Guidelines for creating well-structured GitHub issues and PRs for Lighthouse.
|
||||
|
||||
## Issue Structure
|
||||
|
||||
### Start with Description
|
||||
|
||||
Always begin with `## Description`:
|
||||
|
||||
```markdown
|
||||
## Description
|
||||
|
||||
We presently prune all knowledge of non-canonical blocks once they conflict with
|
||||
finalization. The pruning is not always immediate, fork choice currently prunes
|
||||
once the number of nodes reaches a threshold of 256.
|
||||
|
||||
It would be nice to develop a simple system for handling messages relating to
|
||||
blocks that are non-canonical.
|
||||
```
|
||||
|
||||
**Guidelines:**
|
||||
- First paragraph: problem and brief solution
|
||||
- Provide context about current behavior
|
||||
- Link to related issues, PRs, or specs
|
||||
- Be technical and specific
|
||||
|
||||
### Steps to Resolve (when applicable)
|
||||
|
||||
```markdown
|
||||
## Steps to resolve
|
||||
|
||||
I see two ways to fix this: a strict approach, and a pragmatic one.
|
||||
|
||||
The strict approach would only check once the slot is finalized. This would have
|
||||
0 false positives, but would be slower to detect missed blocks.
|
||||
|
||||
The pragmatic approach might be to only process `BeaconState`s from the canonical
|
||||
chain. I don't have a strong preference between approaches.
|
||||
```
|
||||
|
||||
**Guidelines:**
|
||||
- Don't be overly prescriptive - present options
|
||||
- Mention relevant constraints
|
||||
- It's okay to say "I don't have a strong preference"
|
||||
|
||||
### Optional Sections
|
||||
|
||||
- `## Additional Info` - Edge cases, related issues
|
||||
- `## Metrics` - Performance data, observations
|
||||
- `## Version` - For bug reports
|
||||
|
||||
## Code References
|
||||
|
||||
**Use GitHub permalinks with commit hashes** so code renders properly:
|
||||
|
||||
```
|
||||
https://github.com/sigp/lighthouse/blob/261322c3e3ee/beacon_node/beacon_processor/src/lib.rs#L809
|
||||
```
|
||||
|
||||
Get commit hash: `git rev-parse unstable`
|
||||
|
||||
For line ranges: `#L809-L825`
|
||||
|
||||
## Writing Style
|
||||
|
||||
### Be Natural and Concise
|
||||
- Direct and objective
|
||||
- Precise technical terminology
|
||||
- Avoid AI-sounding language
|
||||
|
||||
### Be Honest About Uncertainty
|
||||
- Don't guess - ask questions
|
||||
- Use tentative language when appropriate ("might", "I think")
|
||||
- Present multiple options without picking one
|
||||
|
||||
### Think About Trade-offs
|
||||
- Present multiple approaches
|
||||
- Discuss pros and cons
|
||||
- Consider backward compatibility
|
||||
- Note performance implications
|
||||
|
||||
## Labels
|
||||
|
||||
**Type:** `bug`, `enhancement`, `optimization`, `code-quality`, `security`, `RFC`
|
||||
|
||||
**Component:** `database`, `HTTP-API`, `fork-choice`, `beacon-processor`, etc.
|
||||
|
||||
**Effort:** `good first issue`, `low-hanging-fruit`, `major-task`
|
||||
|
||||
## Pull Request Guidelines
|
||||
|
||||
```markdown
|
||||
## Description
|
||||
|
||||
[What does this PR do? Why is it needed? Be concise and technical.]
|
||||
|
||||
Closes #[issue-number]
|
||||
|
||||
## Additional Info
|
||||
|
||||
[Breaking changes, performance impacts, migration steps, etc.]
|
||||
```
|
||||
|
||||
### Commit Messages
|
||||
|
||||
Format:
|
||||
- First line: Brief summary (imperative mood)
|
||||
- Blank line
|
||||
- Additional details if needed
|
||||
|
||||
```
|
||||
Add custody info API for data columns
|
||||
|
||||
Implements `/lighthouse/custody/info` endpoint that returns custody group
|
||||
count, custodied columns, and earliest available data column slot.
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- Vague descriptions without details
|
||||
- No code references when describing code
|
||||
- Premature solutions without understanding the problem
|
||||
- Making claims without validating against codebase
|
||||
|
||||
## Good Examples
|
||||
|
||||
- https://github.com/sigp/lighthouse/issues/6120
|
||||
- https://github.com/sigp/lighthouse/issues/4388
|
||||
- https://github.com/sigp/lighthouse/issues/8216
|
||||
Reference in New Issue
Block a user