Instructed

Min-maxing the vibe. Find the best instructions to generate the best results while vibe coding. Create instruction playlists to quickly get running on a new app.

Comment

Inspiration

AI coding tools are fast, but consistency is still a real problem. One run gives camelCase, the next gives snake_case. One file includes robust error handling, another skips it. Teams spend too much time cleaning up code that technically works but does not match internal standards. Instructed exists to close that gap by making team conventions explicit, portable, and usable by any major AI coding tool.

What it does

Instructed is a platform for creating, sharing, and managing Markdown instruction files for AI coding tools. Teams define standards once: naming, structure, error handling, test expectations, and reuse them across projects.

Instructions can be grouped into playlists like React Frontend, Go API, or Testing Standards. Playlists can stay private or be published to the community.

With one CLI command, instructed import, instructions are written into the right file for each tool:

  • CLAUDE.md for Claude Code
  • GEMINI.md for Gemini CLI
  • AGENTS.md for OpenAI Codex
  • .github/copilot-instructions.md for GitHub Copilot

Your standards live in the repo, so the AI tool reads them where it already expects project context.

How we built it

Web platform

Built with Next.js 14 App Router, Firebase Auth, Firestore, and Tailwind CSS. Gemini 3 powers instruction generation, style extraction, and code analysis. Users create and manage Markdown instructions in an editor with live preview.

CLI

Built in Python with Click, httpx, and Rich, then packaged as a standalone binary via PyInstaller. No Python runtime is required for end users. The CLI talks to api.instructed.dev, which handles auth, pagination, and access control. Import operations use atomic writes plus structured HTML markers for reliable dedupe and sync behavior.

Challenges we ran into

  • Multi-target file writing: Every AI tool expects a different file path and format, so we built a target abstraction layer with consistent behavior and atomic writes.
  • Firestore to REST migration: Our early CLI queried Firestore directly. Moving to a proper API simplified the client but required a full backend and data flow redesign.
  • Binary distribution: Shipping single-file executables for Linux amd64/arm64, macOS Intel/Apple Silicon, and Windows through GitHub Actions plus installer flows took serious DevOps work.
  • Playlist resolution: Mixed public/private playlists required clear access handling. We built a /resolve endpoint so the CLI can resolve, skip, and report in one request.

Accomplishments we are proud of

  • One command, four AI tools: instructed import <id> --all writes standards into Claude Code, Gemini CLI, OpenAI Codex, and GitHub Copilot in one step.
  • Real code to real instructions: Gemini 3 can analyze production code and generate instruction files that teams can actually use.
  • Community library: Public instructions are discoverable, votable, and importable.
  • Zero-runtime CLI: Install via shell script or Homebrew, no Python setup needed.

What we learned

  • Markdown is a strong format for AI instructions because it is readable, versionable, and already supported by major tools.
  • The jump from "AI writes code" to "AI writes code our team approves" is mostly an instruction-quality problem.
  • Atomic writes and parseable markers are critical for trust and for reliable sync/remove operations.

What is next for Instructed

  • instructed sync: Update imported instructions when upstream versions change.
  • Team workspaces: Shared libraries with role-based access for larger engineering orgs.
  • IDE extensions: VS Code and JetBrains support for browsing and importing in-editor.
  • Instruction analytics: Measure adoption and impact on review cycles.
  • More Gemini 3 integration: Detect drift between code and instructions, suggest instruction updates, and generate instructions from PR feedback.

Built With

Share this project:

Updates