Skip to content
Back to search

ai-engineering-first-steps

First steps for building an app with Claude Code: a guided interview that turns your idea into a documented set of product and architecture decisions.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/samuel-hornik--ai-engineering-first-steps/badge.svg)](/listings/samuel-hornik--ai-engineering-first-steps)

HTML

<a href="/listings/samuel-hornik--ai-engineering-first-steps"><img src="/api/listings/samuel-hornik--ai-engineering-first-steps/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Inside Claude Code:

/plugin marketplace add samuel-hornik/ai-engineering-first-steps
/plugin install first-steps@ai-engineering-first-steps

Restart Claude Code if the command doesn't show up right away.

<details> <summary>Try it without installing</summary>

git clone https://github.com/samuel-hornik/ai-engineering-first-steps.git
claude --plugin-dir ./ai-engineering-first-steps

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 17 lines
  1. {
  2. "name": "ai-engineering-first-steps",
  3. "description": "First steps for building an app with Claude Code: a guided interview that turns your idea into a documented set of product and architecture decisions.",
  4. "owner": {
  5. "name": "Samuel Horník",
  6. "url": "https://github.com/samuel-hornik"
  7. },
  8. "plugins": [
  9. {
  10. "name": "first-steps",
  11. "source": "./",
  12. "description": "Interview → suggested tech baseline → your decisions → first-decisions.md, referenced from CLAUDE.md.",
  13. "version": "1.0.0",
  14. "category": "productivity"
  15. }
  16. ]
  17. }
README.md · README · 189 lines
  1. <div align="center">
  2. # AI Engineering: First Steps
  3. **Make the big decisions before Claude writes a line of code.**
  4. A Claude Code plugin that interviews you about your app, proposes a complete technical baseline, lets you confirm every choice, and saves it all to `first-decisions.md`: one file Claude reads before every plan and every feature.
  5. [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
  6. [![Claude Code plugin](https://img.shields.io/badge/Claude_Code-plugin-d97757)](https://docs.claude.com/en/docs/claude-code/plugins)
  7. ![Version](https://img.shields.io/badge/version-1.0.0-informational)
  8. ```
  9. /first-steps
  10. ```
  11. </div>
  12. ---
  13. ## Why
  14. When you start an app with an AI coding agent, the important decisions get made by accident. The framework is whatever the first prompt implied, the database is whatever came up first, and auth, caching, logging and testing are left for "later". Three sessions in, Claude is working against choices nobody actually made, and every new session starts from zero.
  15. **First Steps** runs a short kickoff instead. You answer a few questions, Claude proposes a full engineering baseline that fits *your* app, and you confirm or change each part. The outcome is written down where Claude will find it every time.
  16. ## How it works
  17. ```mermaid
  18. flowchart TD
  19. A["/first-steps"] --> B{"Existing code or<br/>first-decisions.md?"}
  20. B -- "code found" --> C["Detect the current stack<br/>and pre-fill it"]
  21. B -- "doc found" --> D["Update mode:<br/>revisit chosen areas"]
  22. B -- "empty folder" --> E
  23. C --> E["Round 1: What is the app?<br/>(4+ questions)"]
  24. E --> F["First suggestion across<br/>every engineering area"]
  25. F --> G["Round 2: Decide what matters<br/>(4+ questions, suggestion = top option)"]
  26. D --> G
  27. G --> H{"Enough context?"}
  28. H -- "gaps or conflicts" --> I["More questions"] --> H
  29. H -- "yes" --> J["Optional extras?<br/>(diagrams, data model, roadmap, open questions)"]
  30. J --> K["Write first-decisions.md"]
  31. K --> L["Point CLAUDE.md at it"]
  32. ```
  33. ### 1. Look before asking
  34. If the folder already has code, the plugin scans manifests and config (`package.json`, `prisma/`, `Dockerfile`, `.github/workflows/`, …), tells you what it found, and only asks about what's missing. If `first-decisions.md` already exists, it offers to **update** it instead of starting over.
  35. ### 2. Round 1: what is the app? (at least 4 questions)
  36. One open question: *what does it do, who is it for, what must it do well?* Then a quick multiple-choice round:
  37. - **Platforms**: web, iOS, Android, desktop
  38. - **Your experience**: beginner, some, experienced *(this sets how technical the rest of the interview gets)*
  39. - **Scale**: prototype → 100k+ users
  40. - **Team & timeline**: weekend solo project → funded company
  41. …plus follow-ups only when needed: accounts and roles, business model, data sensitivity, real-time/offline/AI needs, look & feel.
  42. ### 3. A first suggestion for every area
  43. Claude drafts a baseline across **20 areas** and shows it as one table, with a one-line reason for each choice.
  44. ### 4. Round 2: decide what matters (at least 4 questions)
  45. Questions are ordered by **impact × uncertainty**, so the expensive-to-change decisions (frontend approach, backend, database, auth, hosting) come first. In every question **Claude's suggestion is the first option**, marked *(Recommended)*, with real alternatives and their trade-offs next to it. Anything not asked about is listed so you can accept it as-is or pick areas to change.
  46. ### 5. Enough context? If not, it keeps asking
  47. Before writing, Claude checks that it can state the purpose, users and platforms, knows the MVP features and main user flow, knows the core data and who can access it, has a decision for every area, and finds no contradictions (e.g. *"works offline"* with no local storage plan). Anything missing gets another round. If you say *"you decide"*, it stops asking and records its recommendations as defaults.
  48. ### 6. Optional extras (off by default)
  49. You choose whether the document also gets:
  50. - **Architecture diagrams** (Mermaid, renders on GitHub)
  51. - **Data model sketch**
  52. - **MVP roadmap** that Claude can build phase by phase
  53. - **Open questions log**
  54. ### 7. The output
  55. - **`first-decisions.md`** in your project root: overview, MVP features, user flows, look & feel, a decisions-at-a-glance table, and for every decision *what / why / alternative considered / when to revisit*, a cost estimate, and a decision log.
  56. - **`CLAUDE.md`** gets a short, marked block telling Claude to read `first-decisions.md` before planning or building, to follow it, and to log any changes there. Re-running the command replaces the block instead of duplicating it.
  57. 👉 **See a full example:** [`examples/first-decisions.example.md`](examples/first-decisions.example.md)
  58. ## What it covers
  59. | Group | Areas |
  60. |---|---|
  61. | **Product** | Core features & user flows · Look & feel (UI/UX) |
  62. | **Architecture** | System design · System architecture · Frontend · Hosting & cloud |
  63. | **Backend & data** | API & backend logic · Databases & storage · Auth & permissions |
  64. | **Protection & performance** | Security · Rate limiting · Caching & CDN · Scaling |
  65. | **Operations** | CI/CD & version control · Error tracking & logs · Monitoring & alerts · Testing |
  66. | **Extras** | Payments, email, push, search, uploads, analytics · AI / LLM features *(only if your app uses AI)* · Cost & budget |
  67. Each area comes with defaults that change with your answers: a solo beginner building a web MVP gets managed, all-in-one services; an experienced team targeting 100k+ users gets a scaling path and more control. The full playbook lives in [`skills/first-steps/references/categories.md`](skills/first-steps/references/categories.md).
  68. ## Installation
  69. Inside Claude Code:
  70. ```
  71. /plugin marketplace add samuel-hornik/ai-engineering-first-steps
  72. ```
  73. ```
  74. /plugin install first-steps@ai-engineering-first-steps
  75. ```
  76. Restart Claude Code if the command doesn't show up right away.
  77. <details>
  78. <summary>Try it without installing</summary>
  79. ```bash
  80. git clone https://github.com/samuel-hornik/ai-engineering-first-steps.git
  81. ```
  82. ```bash
  83. claude --plugin-dir ./ai-engineering-first-steps
  84. ```
  85. </details>
  86. ## Usage
  87. Open Claude Code in your project folder (empty or not) and run:
  88. ```
  89. /first-steps
  90. ```
  91. Or give it a head start:
  92. ```
  93. /first-steps a marketplace where people order cakes from home bakers nearby
  94. ```
  95. If another plugin also has a `first-steps` command, use the namespaced form: `/first-steps:first-steps`.
  96. ### After the interview
  97. `first-decisions.md` is now Claude's reference. Good next steps:
  98. - **Plan mode** (`Shift+Tab`): *"Plan the MVP from first-decisions.md."*
  99. - **Build directly:** *"Build phase 1 of the roadmap."*
  100. - **Change your mind later:** run `/first-steps` again and choose **Update**. It revisits only the areas you pick and adds an entry to the decision log.
  101. Want the whole document loaded into every session instead of read on demand? Add `@first-decisions.md` on its own line in `CLAUDE.md` (Claude Code's import syntax). This uses more context per session.
  102. ## Design principles
  103. - **Opinionated, not dogmatic.** It always recommends something, says why, and shows the alternative.
  104. - **Boring technology first.** Well-documented, widely used, managed services unless your answers call for more.
  105. - **Adapts to you.** Beginners get plain-language explanations and fewer moving parts; experienced engineers get terse questions and advanced options.
  106. - **Your language.** The interview and the document follow the language you write in.
  107. - **Documents, doesn't build.** The command ends with the document. Building is your next prompt.
  108. ## Repository layout
  109. ```
  110. .
  111. ├── .claude-plugin/
  112. │ ├── plugin.json # plugin manifest
  113. │ └── marketplace.json # makes this repo installable as a marketplace
  114. ├── skills/
  115. │ └── first-steps/
  116. │ ├── SKILL.md # the /first-steps command: interview flow and rules
  117. │ └── references/
  118. │ ├── categories.md # the 20 decision areas, defaults and signals
  119. │ └── template.md # structure of first-decisions.md
  120. ├── examples/
  121. │ └── first-decisions.example.md
  122. ├── LICENSE
  123. └── README.md
  124. ```
  125. ## Customizing
  126. Fork it and edit:
  127. - **`references/categories.md`** to change the default stack (e.g. your company's standard cloud, framework or auth provider).
  128. - **`references/template.md`** to change the document's structure.
  129. - **`SKILL.md`** to change the interview: number of rounds, questions, or where files are written.
  130. ## Contributing
  131. Issues and pull requests are welcome, especially better defaults, new decision areas, and example outputs for different kinds of apps.
  132. ## License
  133. [Apache License 2.0](LICENSE) © Samuel Horník
  134. Made by [Samuel Horník](https://github.com/samuel-hornik).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.