RFC: Standardize Vue 3 development patterns in AGENTS.md#4865
RFC: Standardize Vue 3 development patterns in AGENTS.md#4865Erics1337 wants to merge 3 commits intobetaflight:masterfrom
Conversation
This RFC proposes adopting standard development instructions for AI agents and developers to support the incremental migration to Vue 3 and TypeScript. Key points: - Incremental adoption of TypeScript (mix of JS/TS allowed). - Strict adherence to Single File Components (SFC) for all new styles. - Generic `AGENTS.md` location for broad tool compatibility (Windsurf, etc.). Based on github/awesome-copilot instructions but adapted for the current codebase state.
WalkthroughAdds a new RFC-style documentation file Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~15 minutes 🚥 Pre-merge checks | ✅ 3 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
🧪 Generate unit tests (beta)
⚔️ Resolve merge conflicts (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Fix all issues with AI agents
In `@AGENTS.md`:
- Line 63: Remove the Nuxt-specific mention of useAsyncData from the AGENTS.md
recommendation: clarify that the project uses Vite + Vue 3 and that useAsyncData
is not available here, and either delete the suggestion "Use `useAsyncData` or
third-party data utilities (Vue Query)" or replace it with a Vite-appropriate
alternative (e.g., recommend using Vue Query, plain fetch with reactive state,
or other composables) and add a note that useAsyncData only applies if migrating
to Nuxt (reference symbols: useAsyncData, Vue Query).
- Line 102: Replace the specific library recommendation ("VeeValidate" and
"@vueuse/form") in the AGENTS.md line that suggests declarative validation with
a generic guidance phrase; update the sentence to something like "Use validation
libraries or build custom validation composables for declarative validation" so
it no longer prescribes unadopted dependencies and avoids encouraging adding
VeeValidate or `@vueuse/form` to the project.
- Line 86: Remove the framework-specific suggestion "useFetch" and the unrelated
"Vue Query" reference and replace with guidance to either implement a
project-specific data-fetching composable (e.g., a custom useFetch built with
the Vue 3 Composition API and the browser Fetch API) or explicitly pick and
document a supported library (name it and add installation/usage notes). Update
the AGENTS.md entry that currently mentions `useFetch` and `Vue Query` to
describe building a custom composable (Composition API + Fetch API) or to state
which third‑party library the project will use, including brief setup and where
to find example usage.
- Around line 117-124: Update the "Testing" section to remove or clearly mark as
optional any tools not present in the repo: remove explicit prescriptive
references to "Cypress", "Playwright", and "axe-core" (or add a note that they
are optional external tools not configured here), and instead state that
"Vitest" is the project's configured test runner and give guidance to write unit
tests with Vue Test Utils and Vitest, mock global plugins (router, Pinia), and
optionally mention end-to-end/accessibility tools as alternatives only if the
developer adds them.
- Line 42: Update the guideline sentence in AGENTS.md that currently says "Use
PascalCase for component names and kebab-case for file names" to recommend
PascalCase for both component names and file names to match the codebase
convention (47 PascalCase Vue component files); ensure the line explicitly
states "Use PascalCase for component names and file names" and adjust any brief
explanatory note to reflect the existing project standard.
🧹 Nitpick comments (3)
AGENTS.md (3)
1-173: Consider adding a dedicated "Migration Strategy" section.While this RFC provides excellent standards for Vue 3 + TypeScript development, it could benefit from a dedicated section on migration strategy that addresses:
JS to TS Migration Path:
- When to add JSDoc annotations vs. full TypeScript conversion
- How to gradually type existing modules
- Handling type inference and
anytypes during transitionOptions API to Composition API Migration:
- Step-by-step conversion patterns
- Handling lifecycle hooks, computed properties, watchers
- Converting mixins to composables
Global to Scoped Styles Migration:
- Identifying global style dependencies
- Extracting component-specific styles
- Handling shared design tokens
Testing During Migration:
- Ensuring behavioral equivalence
- Regression testing strategy
- Incremental testing approach
This would make the document more actionable for developers actively migrating components.
32-32: Clarify mechanism for enabling strict mode on new files only.The guidance to "Enable
strictmode intsconfig.jsonfor new parts of the codebase" needs clarification. TypeScript's strict mode is typically project-wide. Consider specifying the intended approach:
- Option 1: Use per-file
//@ts-checkand `// `@ts-strictdirectives- Option 2: Create separate
tsconfigfiles with different strict settings for new vs. legacy code- Option 3: Use ESLint rules to enforce stricter checking on new files
This clarification will help developers implement the incremental TypeScript adoption correctly.
75-140: Consider marking advanced topics as "Future Considerations."The sections on Performance Optimization, Error Handling, Security, and Accessibility (lines 75-140) contain valuable best practices but may be too prescriptive for an incremental migration RFC. Consider:
- Restructuring these as "Advanced Topics" or "Future Enhancements" to distinguish them from core migration requirements
- Removing tool-specific recommendations (e.g., Sentry/LogRocket on line 98) unless they're actively being adopted
- Focusing the main RFC on migration essentials: TypeScript adoption, Composition API, scoped styles, and Pinia state management
This would keep the RFC focused on actionable migration guidance while preserving these best practices as aspirational goals.
| ### Testing | ||
|
|
||
| - Write unit tests with Vue Test Utils and Vitest | ||
| - Focus on behavior, not implementation details | ||
| - Use `mount` and `shallowMount` for component isolation | ||
| - Mock global plugins (router, Pinia) as needed | ||
| - Add end-to-end tests with Cypress or Playwright | ||
| - Test accessibility using axe-core integration |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Check for testing framework dependencies and configuration
echo "=== Checking package.json for testing libraries ==="
if [ -f "package.json" ]; then
cat package.json | jq '.dependencies, .devDependencies' 2>/dev/null | grep -iE "(vitest|jest|cypress|playwright|mocha|axe|testing-library)" || echo "No matches found in package.json"
else
echo "package.json not found"
fi
echo -e "\n=== Checking for test configuration files ==="
fd -t f "(vitest|vite|cypress|playwright|jest|mocha)\.config\.(ts|js|mjs)" -d 2 2>/dev/null || echo "No test config files found"
echo -e "\n=== Checking for test files ==="
fd -e spec.ts -e spec.js -e test.ts -e test.js 2>/dev/null | head -20 || echo "No test files found"
echo -e "\n=== Full package.json devDependencies ==="
if [ -f "package.json" ]; then
cat package.json | jq '.devDependencies' 2>/dev/null
fiRepository: betaflight/betaflight-configurator
Length of output: 1611
Remove or clarify testing tools not in the project setup.
The document prescribes Cypress, Playwright, and axe-core, but these tools are not in the project's devDependencies. Only Vitest is actually configured and available. Remove references to unavailable tools or clarify they are optional alternatives not set up in the project. If applicable, update the testing guidance to reflect what's actually installed (Vitest).
🤖 Prompt for AI Agents
In `@AGENTS.md` around lines 117 - 124, Update the "Testing" section to remove or
clearly mark as optional any tools not present in the repo: remove explicit
prescriptive references to "Cypress", "Playwright", and "axe-core" (or add a
note that they are optional external tools not configured here), and instead
state that "Vitest" is the project's configured test runner and give guidance to
write unit tests with Vue Test Utils and Vitest, mock global plugins (router,
Pinia), and optionally mention end-to-end/accessibility tools as alternatives
only if the developer adds them.
Updated naming convention for file names in component design.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@AGENTS.md`:
- Line 69: Update the AGENTS.md entry that currently recommends "Tailwind CSS":
either remove the Tailwind CSS sentence entirely or reword it to be generic
(e.g., "Consider utility-first CSS or BEM conventions for class naming") or move
the recommendation into a "Future considerations" section with a note that
Tailwind is not configured in this project; ensure the change references the
existing "Tailwind CSS" text so the reviewer can locate and edit that exact
phrase.
🧹 Nitpick comments (3)
AGENTS.md (3)
15-15: Clarify that Vite is the project's build tool.The line states "Modern build tooling (Vite recommended)" which suggests Vite is optional. Since the project uses Vite as its build system, update this to definitively state "Vite for build tooling" to avoid ambiguity for developers and AI agents following these guidelines.
📝 Suggested clarification
-- Modern build tooling (Vite recommended) +- Vite for build tooling
1-173: Consider adding project-specific examples and context.While this RFC provides comprehensive Vue 3 guidance, it reads as a generic framework guide. To make it more actionable for betaflight-configurator developers, consider adding:
- References to existing migrated components (e.g., OsdTab.vue) as examples
- Specific guidance on migrating legacy tabs from JavaScript to Vue SFCs
- Links to actual project structure (src/components/, src/composables/)
- Notes about coexisting with legacy code during incremental migration
- Examples from the codebase that demonstrate recommended patterns
Based on learnings, migration PRs should focus on correctness and structure without adding new features, so the RFC could explicitly state this principle.
78-78: Clarify the experimental status of<Suspense>in Vue 3.
<Suspense>remains experimental in Vue 3 as of 2026, with no guarantee of stabilization and API subject to change. Add a note to flag this risk to users.Suggested change
-- Use `<Suspense>` for async component loading fallbacks +- Use `<Suspense>` for async component loading fallbacks (⚠️ experimental, API may change)
|
|
||
| - **Strictly Use SFC**: Use `<style scoped>` within Single File Components (`.vue`). | ||
| - **Avoid Global Styles**: Do not use global LESS/CSS files for component-specific styles. | ||
| - Consider utility-first frameworks (Tailwind CSS) for rapid styling |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check for Tailwind CSS in dependencies and configuration
echo "=== Checking package.json for Tailwind ==="
if [ -f "package.json" ]; then
cat package.json | jq '.dependencies, .devDependencies' | grep -i tailwind || echo "Tailwind not found in dependencies"
fi
echo -e "\n=== Checking for Tailwind config files ==="
fd -t f "tailwind\.config\.(js|ts|cjs|mjs)" -d 2 || echo "No Tailwind config found"
echo -e "\n=== Checking for Tailwind imports in code ==="
rg "@tailwind|tailwindcss" --type vue --type js --type ts --type css -g '!node_modules' | head -10 || echo "No Tailwind usage found"Repository: betaflight/betaflight-configurator
Length of output: 291
Remove or contextualize the Tailwind CSS recommendation on line 69.
Tailwind CSS is not configured in the project (verified: no dependencies, no config files, no imports). Recommending it without context suggests adopting a significant framework that isn't part of the current setup. Either remove this reference, make it more generic ("Consider utility-first CSS or BEM conventions for class naming"), or move it to a "Future considerations" section if relevant to longer-term goals.
🤖 Prompt for AI Agents
In `@AGENTS.md` at line 69, Update the AGENTS.md entry that currently recommends
"Tailwind CSS": either remove the Tailwind CSS sentence entirely or reword it to
be generic (e.g., "Consider utility-first CSS or BEM conventions for class
naming") or move the recommendation into a "Future considerations" section with
a note that Tailwind is not configured in this project; ensure the change
references the existing "Tailwind CSS" text so the reviewer can locate and edit
that exact phrase.
Erics1337
changed the title
|
|
🎉 Do you want to test this code? 🎉 |
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In `@AGENTS.md`:
- Around line 31-33: Update the AGENTS.md guidance to explain exactly how to
enable strict mode only for new/TS parts: state that you should add per-folder
or per-package tsconfig.json files that extend the base config and set
"compilerOptions": { "strict": true }, or use TypeScript Project References (add
"composite": true and a "references" entry) for new subprojects; mention that
these per-folder tsconfig files will be picked up by editors/tsc and that the
root tsconfig.json remains unchanged, and optionally note using editor/CI
overrides (tsconfig.json inheritance) to enforce the new strict settings for new
.ts/.vue files.
- Around line 144-146: Update Step 2's wording to avoid implying a fresh Vite
init: replace the line "Initialize Vite project with Vue 3 and TypeScript" with
a phrase that directs contributors to use or verify the existing Vite
configuration (e.g., "Use the repository's existing Vite setup configured for
Vue 3 and TypeScript" or "Ensure Vite is configured for Vue 3 and TypeScript"),
so contributors understand they should adapt or confirm current config rather
than re-initialize a new project.
| - **Incremental Adoption**: Existing JS files are common. When modifying them, prefer JSDoc for types. When creating new files, use `.ts` or `.vue` with `lang="ts"`. | ||
| - Enable `strict` mode in `tsconfig.json` for new parts of the codebase. | ||
| - Use `defineComponent` or `<script setup lang="ts">` with `defineProps` and `defineEmits` |
There was a problem hiding this comment.
Clarify how “strict mode for new parts” is enforced.
tsconfig.json is project-wide; “strict for new parts” typically requires a separate tsconfig (e.g., via project references or per-folder config). Consider spelling out the mechanism to avoid confusion.
🤖 Prompt for AI Agents
In `@AGENTS.md` around lines 31 - 33, Update the AGENTS.md guidance to explain
exactly how to enable strict mode only for new/TS parts: state that you should
add per-folder or per-package tsconfig.json files that extend the base config
and set "compilerOptions": { "strict": true }, or use TypeScript Project
References (add "composite": true and a "references" entry) for new subprojects;
mention that these per-folder tsconfig files will be picked up by editors/tsc
and that the root tsconfig.json remains unchanged, and optionally note using
editor/CI overrides (tsconfig.json inheritance) to enforce the new strict
settings for new .ts/.vue files.
| 1. Plan component and composable architecture | ||
| 2. Initialize Vite project with Vue 3 and TypeScript | ||
| 3. Define Pinia stores and composables |
There was a problem hiding this comment.
Avoid implying a fresh Vite initialization in an existing repo.
Step 2 says “Initialize Vite project,” which reads like a greenfield setup. Consider reframing to “use the existing Vite setup / config” to avoid misleading contributors.
🤖 Prompt for AI Agents
In `@AGENTS.md` around lines 144 - 146, Update Step 2's wording to avoid implying
a fresh Vite init: replace the line "Initialize Vite project with Vue 3 and
TypeScript" with a phrase that directs contributors to use or verify the
existing Vite configuration (e.g., "Use the repository's existing Vite setup
configured for Vue 3 and TypeScript" or "Ensure Vite is configured for Vue 3 and
TypeScript"), so contributors understand they should adapt or confirm current
config rather than re-initialize a new project.
|
I recently saw an analysis suggesting AGENTS.md / CLAUDE.md style files often hurt more than help. The gist was that extra repo-level “agent instructions” can add noise, misdirect models, and benchmark worse than just using the code + a focused prompt. Developer-written context was usually neutral at best, and auto-generated context sometimes made results worse. So this PR is mainly to spark discussion: do we want any agent-specific instruction files here at all? If yes, I’d argue for the smallest, least-prescriptive version possible, and lean on README/CONTRIBUTING plus code structure for “context” instead of long MD guidance. Curious what others have seen in practice. |
|
Agree instead of trying to control the whole process minimal constraints would be probably more effective. What non-obvious, enforceable constraints are not already expressed in code? Perhaps a minimal file with directional constraints: Post migration we could use structural constraints: |
3 participants
Vue 3 Development Instructions
These standardized instructions are adapted from the awesome-copilot Vue 3 instructions.
Modifications & deviations
These agent instruction have adopted most of the upstream instructions, with the following project-specific adjustments:
Current State
The codebase largely complies with these instructions, with some known exceptions:
This PR establishes the baseline for agent based vue 3 development standards going forward.