ColoredCow / ColoredCow/engineering-recipes
Code review guideline: flag custom scripts that duplicate framework built-ins
- Dominant language
- Shell
- Stars
- 1
- Forks
- 2
- PR merge metrics
- No merged PRs in 30d
Description
## Context
This builds on the [automated-code-review recipe](https://github.com/ColoredCow/engineering-recipes/tree/main/automated-code-review). That recipe lets teams drop guideline markdown files into `docs/code-review/` — Claude reads them before reviewing every PR.
A pattern that keeps appearing across projects (Django, Laravel, WordPress, Node, .NET) is developers writing **custom scripts, commands, or utilities for things the framework already ships natively**. This adds maintenance burden and creates confusion for new developers.
This issue proposes adding a reusable guideline snippet to the `automated-code-review/templates/` directory so any team can drop it into their `docs/code-review/` and have Claude catch this automatically on every PR.
---
## Proposed guideline snippet
Add this to your project's `docs/code-review/` directory as `avoid-reinventing-framework-builtins.md`:
~~~md
## Avoid reinventing framework built-ins
Flag any code that implements functionality the project's framework or platform already provides natively. Suggest the built-in alternative and link to the official docs.
### Django
- Custom management commands that replicate `createsuperuser`, `migrate`, `collectstatic`, `shell`, `dbshell`, or other built-in commands → suggest using the built-in
- Manual static file serving setup → check that `django.contrib.staticfiles` is in `INSTALLED_APPS` and `STATIC_URL` is set
- Custom user creation scripts → `python manage.py createsuperuser` (supports `--no-input` with env vars for CI)
### Laravel
- Scripts that set `APP_KEY` manually → `php artisan key:generate`
- One-off SQL or PHP scripts for seeding dev/test data → `php artisan db:seed`
- Custom symlink scripts for file storage → `php artisan storage:link`
- Manually writing migration SQL → `php artisan make:migration`
### Node.js / npm / yarn
- Shell wrapper scripts for recurring project tasks → `package.json` scripts (`dev`, `build`, `test`, `lint`)
- Custom env validation on startup when the framework provides it → NestJS `@nestjs/config`, Next.js built-in env validation, `dotenv` for plain Node
### WordPress
- Custom PHP or SQL scripts for setup tasks (create admin, activate plugins, flush cache) → WP-CLI (`wp user create`, `wp plugin install`, `wp cache flush`)
- Manual option updates via SQL → `wp option update`
### .NET
- Raw SQL migration files → `dotnet ef migrations add` / `dotnet ef database update`
- Boilerplate controllers, views, or models written by hand → `dotnet aspnet-codegenerator`
### General signals to flag (any stack)
- A file named `setup_admin.*`, `init_db.*`, `create_user.*`, `seed.*`, or similar in the project root or scripts directory — verify these aren't duplicating a framework CLI command
- Comments like `# workaround because the built-in doesn't support X` without linking to the docs — ask the author to confirm the built-in truly lacks the feature
~~~
---
## What this catches in practice
**Example (Django) — caught on PR review:**
```python
# apps/user/management/commands/ensure_superuser.py
class Command(BaseCommand):
def handle(self, *args, **kwargs):
email = os.environ['DJANGO_SUPERUSER_EMAIL']
password = os.environ['DJANGO_SUPERUSER_PASSWORD']
User.objects.create_superuser(email=email, password=password)
```
Claude flags: *"Django ships `createsuperuser --no-input` which reads `DJANGO_SUPERUSER_EMAIL` and `DJANGO_SUPERUSER_PASSWORD` from env vars natively. This command can be removed."*
**Example (Laravel) — caught on PR review:**
```php
// scripts/setup.php
Artisan::call('config:cache');
file_put_contents(base_path('.env'), str_replace('APP_KEY=', 'APP_KEY=' . Str::random(32), ...));
```
Claude flags: *"`php artisan key:generate` handles this. The custom script may produce an invalid key format."*
---
## Proposal
Add `avoid-reinventing-framework-builtins.md` to `automated-code-review/templates/` so teams can copy it into `docs/code-review/` alongside the existing `review-guidelines.md`. Teams can trim it to the sections relevant to their stack.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.