ColoredCow / ColoredCow/engineering-recipes

Code review guideline: flag custom scripts that duplicate framework built-ins

Open
#8 0 comments 0 reactions 2 assignees Claimed by @rathorevaibhav View on GitHub
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.