Add AGENTS.md style guide for AI code reviewers#3087
Merged
Conversation
Captures writing style conventions in AGENTS.md so GitHub Copilot, Cursor, Windsurf, and Claude-based tools apply consistent voice guidance during code review and content creation. AGENTS.md is the standard convention recognized across all modern AI-assisted development platforms.
There was a problem hiding this comment.
Pull request overview
Adds an AGENTS.md writing style guide to standardize Elixir School’s voice and formatting for AI-assisted tooling during reviews and content creation.
Changes:
- Introduces a voice/tonality overview for Elixir School writing.
- Defines concrete do/don’t rules, sentence patterns, and vocabulary cues.
- Documents formatting and content-architecture expectations for lessons and blog posts.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
| - **Links**: Inline markdown links with descriptive text, never "click here." | ||
| - **Bold**: For key terms on first introduction or for emphasis in lists. Never for entire sentences. | ||
| - **Italics**: For asides, book/movie titles, or gentle emphasis. | ||
| - **Horizontal rules** (---): Before closing/signature sections only. |
|
|
||
| ## Voice Overview | ||
|
|
||
| Elixir School's voice reads like a senior engineer talking to peers at a whiteboard: technically precise but never stuffy. We respect the reader's intelligence without assuming they know everything. We are direct and opinionated — we tell you what works and what does not, and why. The writing is warm, collaborative, and efficient. We get to the point quickly, let code do the heavy lifting, and trust the reader to keep up. |
| - Present tense for describing behavior: "Release Please maintains Release PRs that are kept up-to-date" | ||
| - Contractions always ("we'll", "you're", "it's", "don't") — never "we will" or "do not" unless for deliberate emphasis | ||
|
|
||
| ### What We Do NOT Do |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Captures Elixir School's writing style conventions in AGENTS.md so GitHub Copilot, Cursor, Windsurf, and Claude-based tools apply consistent voice guidance during code review and content creation. AGENTS.md is the standard convention recognized across modern AI-assisted development platforms, providing wider coverage than CLAUDE.md alone.