kinhluan code-author ✍️
Keyword: author | Platforms: gemini,claude,codex
Expert AI Agent Skill for Code Authoring - Best practices for creating, describing, and refining code changes based on Google's Engineering Practices.
🎯 Core Mandates (The Author's Rules)
- Small CLs Only: Keep changes focused on ONE thing. Small CLs are easier to review, faster to merge, and lower risk.
- Clear Descriptions: Always explain WHAT is changing and WHY. The "How" should be evident from the code, but the "Why" is critical context.
- Risk Areas Identification: Explicitly call out parts of the code where you are unsure or where there is a high risk of side effects.
- No Refactor + Feature Mix: Never mix refactoring with new features or bug fixes. These must be separate CLs.
- Proactive Communication: Address all reviewer comments, even if you disagree. Explain your reasoning clearly and professionally.
- Self-Audit First: Run the "Self-Audit Checklist" before sending a CL for review.
🛠 Authoring Workflows
1. Planning a Change (CL)
- Isolate the Task: Can this be broken into smaller, independent steps?
- Draft the Description: Start with a one-line summary. Add context on the problem being solved.
- Identify Risks: Note any areas that need extra attention from the reviewer.
2. Writing the Code & Self-Audit
- Tests First: Ensure the change is covered by automated tests.
- Style Consistency: Follow Google Java Style.
- Self-Audit Checklist:
- Diff Minimization: Revert accidental changes (whitespace, commented-out code).
- Documentation Check: Update README, JSDoc, or JavaDoc for new exports/logic.
- Test Alignment: Ensure tests cover logic branches, not just the "happy path."
- Logic Validation: Mentally trace the execution path for edge cases (null, empty, etc.).
3. Handling Reviewer Feedback
- Be Grateful: Reviewers are spending time to improve your code.
- Don't Take it Personally: The goal is to improve the code, not critique the author.
- Resolve or Disagree: Either apply the change or explain why the current approach is better. Never ignore a comment.
🔍 CL Description Template (Superpowers Edition)
[Summary Line: Brief one-line description]
### 📝 Context & Intent
[Why is this change necessary? What problem does it solve?]
### 🛠 Key Changes
[Bullet points of the main code modifications]
### ⚠️ Risk Areas & Concerns
[Where should the reviewer focus? Any potential side effects or uncertainties?]
### ✅ Verification Results
[List tests run, coverage achieved, and manual verification steps]
[Related Issues: e.g., Fixes #123]
🌐 Knowledge Sources & Deep Dives
Directive: Use
web_fetchto find Google's specific guidance on "Small CLs" or "CL Descriptions" if a change feels too large or complex.
- Developer's Guide: Google Eng Practices - Authoring - The primary source.
- Small CLs: Why Small CLs? - Benefits and strategies.
- CL Descriptions: How to write CL Descriptions - Best practices.
- Handling Feedback: Handling Reviewer Comments - Mindset and communication.
Skill Interoperability
The code-author ✍️ skill ensures that work produced by other skills is packaged correctly:
- java-expert ☕ & quarkus-expert ⚡: Logic produced is split into reviewable CLs.
- refactoring-expert 🛠: Ensures refactors are isolated from feature changes.