Make the project easy to run and change
Establish clear code ownership, reproducible dependencies, safe configuration, and a small verification path.
You inherit the crew scheduler on Monday. You should be able to answer: how do I run this, where does this behavior belong, what must remain true, and how do I check a change?
Start by inspecting the repository. Keep working conventions unless the task reveals a reason to change them.
Why this matters
Setup decisions decide whether the next change is a small edit or an archaeology dig. Unpinned dependencies, secrets in the browser bundle, and missing checks turn every task into debugging the project instead of improving the product.
What to understand
Ownership beats folder aesthetics: reusable behavior, product-specific behavior, and protected server operations — kept close to their consumers, with a shared abstraction only when real consumers justify it. Installs must resolve identically everywhere. Configuration belongs to where the code runs, not the code itself. Types catch wrong assumptions at boundaries; only runtime checks make outside data trustworthy.
Watch for
- Documenting a test command that does not exist.
- Public browser values carrying secrets because the config object was shared whole.
- Treating a preview URL as permission to share production data or credentials.
- Installing an entire testing stack to assert that static text renders.
Strong default
Use the existing package manager, commit its lockfile, and install frozen in CI so undeclared resolution changes fail visibly. Commit an .env.example with names and safe placeholders, validate server config in server-only code, and export only public values to the browser. Keep one lint plus format setup, strict types, and one real slice early.
When this doesn't apply
Route organization depends on the framework, and the scaffold below is responsibilities — not a mandatory layout. Commands differ per repo; this one uses pnpm dev, pnpm check, and pnpm build. Document the runtime version and the actual commands, not the ones you wish it had.
In practice
app/ routes, layouts, loading and error boundaries
components/ui/ product-agnostic styled primitives
features/projects/ project components, state, schemas, and tests
lib/server/ protected data access and integrations
app/globals.css shared visual tokens
AGENTS.md verified commands and important constraintsAsk your agent: "Install exactly what the pinned-version list says, and fail loudly if anything resolves differently."
Ask your agent: "Check that secrets only appear in server-only code, and that the browser only gets public values."
Add a test — test data plus assertions (fixtures) are fine here — for the first behavior that matters, such as denied access or a failed write keeping the user's input. Run a real slice early: route → data read → user action → saved result → failure recovery.
Verify
Run the real slice end to end. Confirm secrets stay server-only, installs resolve identically, and the first behavior that matters has a test plus a recovery path.
Related skills
Use $setup for a new foundation or an existing repository with unclear ownership. Use $git when multiple contributors need to coordinate shared files. Continue with project context for the short map the next task needs.
Last updated on