Summary of "Si programas con IA, necesitas esta estructura de proyecto"

Project structure for AI-assisted development

Key idea

A simple, reusable repository layout that helps AI guidance agents (Cloud/CloudCode or equivalents) understand and operate on your project. The layout combines source code, documentation, automation, and agent skills so agents can read context and run repeatable workflows. It works for frontend, backend, full‑stack, or multi‑repo projects.

Recommended folder / file structure (core elements)

src/ — project source code.
tools/scripts/ — reusable scripts for development tasks (seed data, create users, migrations, test data, etc.).
.cloud/ (or equivalent agent folder) — agent configuration and skills (custom commands the agent can run).
docs/ — human- and agent-readable documentation (architecture, specs, runbooks, decisions).
README.md — project presentation for GitHub.
cloud.md — agent-context file: a project summary and rules loaded by the agent at startup.

cloud.md and initialization

Many guidance agents provide an init (or slash-init) command that scans the repo and auto-generates cloud.md summarizing the stack, architecture, models, commands, patterns, etc.
cloud.md is editable — you should review and adjust it after generation.
Include a Rules section in cloud.md to set agent behavior. For example:

“Don’t build on every change.”
After creating or updating cloud.md, restart the agent/tool so it re-reads the updated context.

docs/ — contents and purpose

Use docs/ for structured, maintained documentation instead of ad‑hoc notes. Recommended contents:

architecture.md — stack overview, ER diagrams, data models, routes/APIs, infra.
decisions/ — records why architecture choices were made (relational vs NoSQL, auth choices, adapters, etc.).
roombooks (runbooks) — how-to guides: deploy, migrations, audit, onboarding steps.
specs — feature specifications and patterns.

Tips:

Prefer specs over many tiny task notes — they make agent requests more precise and repeatable.
Split docs into smaller files by topic for faster navigation and better agent retrieval.
Keep documentation living: update docs/ as the code changes.

tools/scripts — usage

Create scripts to automate repetitive developer tasks: create users, seed example products, clean DB, run migrations, etc.
Scripts improve developer productivity and make testing/development deterministic (for example, a create-user script to seed an admin user).
Scripts can be invoked by agents or by developers locally.
Commit common scripts to the repo so collaborators and agents can reuse them.

.cloud/skills — agent commands

Place agent-executable commands as markdown/config files inside .cloud/skills.
Each skill typically contains:
- name
- description
- steps/instructions
- references to tools (e.g., browser automation)
Use skills for common workflows: test, build, deploy, PR review, browser tests, etc.
Skills can orchestrate multi-step processes (open browser, run tests, fix issues, commit, push).

Example skill usages:

/test — opens Chrome via a browser tool to verify UI components.
/build — runs build steps and optionally commits/pushes changes.

Tooling demonstrated

Cloud / CloudCode (generic “cloud” agent) — used to init the project, create cloud.md, and run skills.
Browser automation tools (e.g., Chrome Tools) — used inside skills for UI verification (requires installation/config).
Prisma — used as an ORM/data modeling example in cloud.md stack.
Next.js (referred to in the demo as “Nexi 16”) — example frontend framework.
Auth & adapters — JWT, social logins, etc., discussed in decisions.
Persistence/memory — to store conversation state or important facts for agents; can be exported to docs.
Hooks/Notifications — webhooks or notifications (Slack/Telegram) for when agent tasks complete (requires configuration).

Example workflows shown

Run init to auto-generate cloud.md and an architecture summary.
Edit cloud.md to set rules and document stack, patterns, and models.
Ask the agent to split a large architecture doc into multiple docs (overview, stack, data models, routes).
Use the agent to create docs/decisions and docs/roombooks; the agent can fill starter content (you should verify and refine).
Create tools/scripts/create-user to seed admin/test users and run it to log in locally.
Create .cloud/skills/test to open a browser, navigate pages, check UI components, and report/fix issues.
Run /build to build, run checks, commit, and push in one command.

Best practices & tips

Keep docs/ and cloud.md up to date as code changes.
Record decisions and runbooks to preserve design rationale and onboarding steps.
Prefer structured specs so agents know exactly which files to read and modify.
Commit skills and scripts to the repo for team reuse.
In monorepos or separated frontend/backend repos, give each service its own cloud.md and skills when teams are separate.
Restart the agent after adding or updating cloud.md so it loads the new context.

Product mention / hosting recommendation

Cynote (hosting platform) was presented as an example hosting option with features such as:

Integrations with GitHub/GitLab and auto-deploy in seconds.
Public URLs, custom domains, automatic HTTPS, WebSockets, and HTTP/2.
Real-time logs, environment variable management, and 24/7 support.
Managed PostgreSQL/MySQL and backend server options starting at lower price tiers, with a 7‑day free trial.

Guides, tutorials, and resources referenced

Video demos covered:
- How to init cloud.md.
- Creating docs, decisions, and runbooks.
- Creating tools/scripts and executing them.
- Creating .cloud/skills and running slash commands (/test, /build).
Additional linked resources in the video description:
- Cynote (hosting).
- Tutorial on skills.
- Tutorial on Chrome Tools installation and usage.
- Discord community: fast.df/discord and other social channels.
Presenter is preparing a course on AI-driven development workflows using these approaches.