Repository navigation
docs(guides): agent prompts come after the human steps - #8352
Merged
Merged
Conversation
The Getting Started > Prisma ORM sidebar now has one Quickstart group with four entries: I'm creating a new app, I have an app but no database yet, I have a database already, and I have a Prisma 7 app. No URL changes. Adds the page pair for an app with an empty database, for PostgreSQL and MongoDB. Extends the PostgreSQL page for an existing database with what contract infer reads, what db sign checks, and the second migration. Each page in a pair names its database and links its twin. The Prisma ORM introduction shows the four starting points as cards, and link text across the docs uses the new page titles. Every command and output block on the new and extended pages comes from a run against prisma 8.0.0-rc.19 and the ORM packages at 8.0.0-rc.13. Agent: nimue-20 Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io> Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…fix reader marks The MongoDB twins and from-scratch were no longer in any meta.json, so they opened with the top-level "All docs" sidebar. A meta.json can now name pages under `hiddenPages`: they belong to that folder, so they keep its section's sidebar, but the sidebar and the previous/next links do not list them. The Quickstart folder uses it for its four hidden pages and still shows exactly four entries. The orphaned add-to-existing-project/meta.json is removed. The PostgreSQL page for an existing database now uses the flags form of orm init, explains which Node.js versions need temporal-polyfill for date and time columns and where the import goes, shows how to model a table in another PostgreSQL schema, and says that db sign fails when a table with row-level security policies has no model. The MongoDB pages say why the id field is _id in queries and results. All four existing-app pages get the fixes from two cold reader rounds. Every new command and output comes from runs against prisma 8.0.0-rc.19 and the ORM packages at 8.0.0-rc.13. Agent: nimue-20 Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io>
… the 24.11 carve-out Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io>
…us and the quickstarts The 'I have an app, but no database yet' flow for PostgreSQL passes every step on Node.js 24.10.0 and 24.11.1 alike (prisma 8.0.0-rc.19, @prisma/orm-postgres 8.0.0-rc.13), so the range is not a known break. 24.11 is where Node.js 24 became a long-term support release. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io>
On /prisma-orm, /getting-started, the ten framework guides, and the two runtime guides, the 'Use with your agent' section moves from before the steps to directly before Next steps. Where a guide also had 'Prompt your coding agent', the two are one section now. The guide rules in making-guides.mdx describe the new order. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io>
…erged guides Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io>
wmadden-electric
added a commit
that referenced
this pull request
Sep 30, 2026
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io>
Contributor
🍈 Lychee Link Check Report205 links: ✅ All links are working!Full Statistics Table
|
Contributor
|
Navigate logical layers of code changes, visualize relationships, and explore their blast radius. Note Currently processing new changes in this PR. This may take a few minutes, please wait... ⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Advanced Run ID: 📒 Files selected for processing (47)
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Advanced Run ID: 📒 Files selected for processing (15)
Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 0 remain after this review. WalkthroughThe PR updates agent-prompt placement and instructions across getting-started pages and framework and runtime guides. It also updates the guide-authoring template to specify the prompt section’s position and format. ChangesAgent prompt documentation
Priority: ➖ Normal Estimated code review effort: 3 (Moderate) | ~20 minutes Change: Other Possibly related PRs
Suggested reviewers: Merge Risk: ⚪ Minimal · up to The documentation reordering has no identified merge-blocking issue. Setup guidance and agent-prompt prerequisites remain intact; merge after normal checks. Architecture SummaryArchitecture risk: 🔵 Low · up to The change affects 1 system. Changed systems: Architecture concerns Review detailsSystems and components
Before / after behavior
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
wmadden
approved these changes
Sep 30, 2026
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Open the Hono guide today and the section straight after Prerequisites is "Use with your agent", a prompt to hand to a coding agent, before a single step a person follows. After this change the guide reads:
The same move applies to
/prisma-orm,/getting-started, the ten framework guides, and the two runtime guides. No prompt text changes.The decision
Human instructions first, the agent prompt last. This is the direct answer to the "the docs are written for AI" complaint in the Prisma ORM 8 docs audit (item A3; slice 04, spec at
docs/orm-docs-audit/slices/04-agent-prompts-last/spec.mdon thedocs/orm8-docs-audit-designbranch, #8243).What changed, step by step
guides/frameworks/astro,elysia,hono,nestjs,nextjs,nuxt,react-router-7,solid-start,sveltekit,tanstack-start,guides/runtimes/bun,deno): the## Use with your agentsection moves to directly before## Next steps. Six of them also had a## Prompt your coding agentsection at the end; on those, the two are now one## Use with your agentsection, in the order prompt block, skills pointer, follow-up prompts. Because the prompt's first step already runsnpx prisma@latest init, the skills pointer now says so and tells a reader who followed the steps by hand to run it once themselves./prisma-orm:## Use with your agentis the last section, after "Learn the concepts"./getting-started: the two prompts leave their sections and sit together in one closing## Use with your agentsection, each with a lead line saying which project it is for. They stay untitled so the.mdrendition keeps one heading (a titled prompt renders as its own heading there).guides/making-guides.mdx: the required sections and the template now read Introduction, Prerequisites, numbered steps, Common gotchas, Use with your agent, Next steps.Verification
/getting-started,/prisma-orm,making-guides.mdx, and the merged guides; one cold reader round on/getting-startedand the Hono guide flagged the two sentences the merge created (now fixed) and pre-existing prompt content, which is out of scope and recorded as E22 and E23 inchanges.mdon the audit branch.lint:links(0 errors),lint:versions(every pinned version current),test(70 pass)./docs/getting-started,/docs/prisma-orm, and/docs/guides/frameworks/honoshow the prompt as the last section before Next steps.Left for a follow-up slice
The guides under
guides/database,guides/deployment,guides/integrations, andguides/switch-to-prisma-orm,composer/porting-an-app.mdx, the full-stack tutorial, and the## Prompt your coding agentsections underorm/follow the same pattern and get the same move once this one is in. Recorded under A3 inchanges.md.Alternatives considered
AgentPrompt, since Docs: one recommended getting-started path for the Prisma stack, for humans and agents #8106); the complaint is its position on the first screen, not its size./getting-started. Thetitleprop only relabels the card on the page but becomes a###heading in the.mdrendition, which would put each lead line above a heading.Stacked on #8350 (base
docs/quickstart-by-starting-point); retarget tomainwhen that merges.Agent: gulliver-20
🤖 Generated with Claude Code
Summary by CodeRabbit