19 added, 18 removed. Audit A to A.
---
name: codebase-simplification-guide
description: >-
Rules and principles for keeping this codebase clean, minimal, maintainable, and free of unnecessary abstractions.
---
# Codebase Simplification & Maintenance Guide
- This skill provides guidelines on how to keep the repository clean, avoid over-engineering, and maintain high developer velocity.
+ This skill provides guidelines on how to keep repositories clean, avoid over-engineering, and maintain high developer velocity.
- ## 1. Branch-First Development
+ ---
+ ## 1. Local Branch-First Development
+
> [!IMPORTANT]
- > **CREATE A LOCAL BRANCH FIRST**: Always start by creating a local branch from `main`:
+ > **CREATE A LOCAL BRANCH FIRST**: Always start by creating a dedicated local branch from `main`:
> ```bash
- > git switch -c MishraShardendu22/main/<feature-name>
+ > git switch -c <developer-or-agent>/main/<feature-name>
> ```
> Never develop or modify code directly on `main`.
---
## 2. Core Principles
- 1. **No Unwanted Infrastructure**:
- * Do not add Dockerfiles, docker-compose, Kubernetes manifests, Nginx configs, Prometheus/Grafana server setups, or Terraform scripts.
- * Everything runs on native Vercel (Next.js, Python FastAPI) and Render (Go Fiber).
+ 1. **Prune Speculative Abstractions**:
+ - Do not create interfaces or wrapper layers that have only a single implementation unless required for mocking in tests.
+ - Prefer straightforward, readable standard library code over heavy external frameworks.
- 2. **No Speculative Abstractions**:
- * Do not create interfaces or wrapper layers that have only a single implementation unless required for mocking in tests.
- * Prefer straightforward, readable standard library code over heavy external frameworks.
+ 2. **Centralized Configuration**:
+ - Never call `os.Getenv` or `process.env` in arbitrary component or handler files.
+ - All environment access must go through dedicated central modules (e.g. `config/env.ts`, `config/settings.py`, `config/config.go`).
- 3. **Centralized Configuration**:
- * Never call `os.Getenv` or `process.env` in arbitrary component files.
- * All environment access must go through the dedicated central module (`backend/config`, `agentic-observatory/config`, `frontend/src/config/env.ts`).
+ 3. **Zero Dead Code**:
+ - Remove unused functions, structs, imports, scripts, and commented-out code during every refactoring pass.
- 4. **Zero Dead Code**:
- * Remove unused functions, structs, imports, scripts, and commented-out code during every refactoring pass.
+ 4. **Safe Database Practices**:
+ - Never drop or truncate production tables.
+ - Always write idempotent migrations (`CREATE TABLE IF NOT EXISTS`).
- 5. **Safe Database Practices**:
- * Never drop or truncate production tables.
- * Always write idempotent migrations (`CREATE TABLE IF NOT EXISTS`).
+ 5. **Pragmatic Tooling**:
+ - Avoid creating custom scripts when existing verified CLI tools (`pnpm`, `uv`, `go`, `docker`) already provide native solutions.