base-next-ai

An AI engineering layer you install onto any existing Next.js project. It is not a starter and not a framework. Claude Code and Codex are the agent runtime; this package is the brain + workflows + guardrails + updater that sits on top.

After Next.js 16.2 / 16.3, Next itself now ships version-matched docs and generates AGENTS.md / CLAUDE.md. So this tool deliberately does not store docs or fight that generation. Instead it provides four things Next does not:

1. A compact refactoring constitution (base-ai-rules), injected without touching Next's own block or your content.
2. The base-next-refactor skill — a behavior-preserving, multi-step refactoring workflow with nine modes.
3. Quality-gate orchestration (lint → type-check → test → build → e2e) that reads your package.json and never invents script names.
4. A unified install/update experience across Claude Code + Codex + CI.

Quick start

cd my-next-project
npx base-next-ai init

init detects your Next.js version and wires everything up idempotently. Then, in your agent:

/base-next-refactor full        # Claude Code
$base-next-refactor full        # Codex

Commands

| Command | What it does | | --- | --- | | base-next-ai init | Detect the project and wire AGENTS.md / CLAUDE.md + skills. Idempotent. | | base-next-ai inspect | Report Next/React version, router, package manager, and detected gate scripts. | | base-next-ai verify | Run the quality gate. --setup checks AI-wiring health instead. | | base-next-ai update | Refresh our rules block + skills without touching your own content. |

Useful flags: --cwd <dir>, --json (inspect), --only lint,build and --keep-going (verify), --no-skills (init/update), --setup (verify).

The ownership contract

The tool is careful about a file Next.js also writes. Each writer owns only its own block:

| Block / file | Owner | | --- | --- | | AGENTS.md → nextjs-agent-rules block | Next.js (re-added on next dev) | | AGENTS.md → base-ai-rules block | this tool | | AGENTS.md → everything else | you | | CLAUDE.md (@AGENTS.md) | Next.js, or this tool as a fallback |

init and update only ever edit the base-ai-rules block. Your content and Next's block are preserved byte-for-byte.

Version handling

| Installed Next.js | Behavior | | --- | --- | | ≥ 16.3 | Next auto-generates the agent files; we inject only our block + skills. | | 16.2 | Docs are bundled; we create AGENTS.md pointing at node_modules/next/dist/docs/. | | ≤ 16.1 | We run the legacy @next/codemod agents-md to fetch docs into .next-docs/. |

The base-next-refactor skill

One skill, nine modes: audit, dead-code, duplication, architecture, nextjs, performance, testing, verify, and full (the master workflow). Every editing mode preserves behavior, records a baseline of pre-existing errors, and gates completion on the quality gate. The performance mode defers to the upstream Vercel react-best-practices skill rather than re-deriving guidance.

Scope (v1)

No MCP server, Vector DB, API, or multi-agent system — those are intentionally out of scope. See PLAN.md for the full architecture and rationale.

License

MIT