Skip to content
Ileen Docs

Writing an Effective Project Brief

Enrich the brief with files and repositories

The briefing form in Content Mode accepts two extra context sources:

  • Reference Documents — drag-and-drop (or click to upload) PDFs, Word, Excel, text files, and images. These become Project Documents and are injected as context in every agent call.
  • Repositories — link one or more git repos (URL, branch, optional PAT). Use this if you want Content Mode to pull release history for changelogs or code-aware marketing copy (e.g. feature announcements based on actual commits).

Add repos with the + Add Repo button and remove them with the trash icon (enabled when more than one repo is linked).

The quality of your project brief directly determines the quality of the architecture plan. This guide shows you what to include, what to avoid, and how to use file attachments effectively.

Applies to: Design Mode — New Project modal and AI Architect chat

What makes a good brief

The AI Architect needs to understand four things:

  1. What you’re building — the type of system and its primary function
  2. Who will use it — personas and their goals
  3. At what scale — users, data volume, geographic spread
  4. With what constraints — budget, timeline, existing systems, compliance

A brief that covers all four consistently produces a better architecture plan than one that is longer but lacks specifics on any of these.

The initial message

The initial message in the New Project modal is your opening statement. Aim for 3–6 sentences:

Good example:

We’re building a multi-vendor e-commerce marketplace for EU small businesses. Vendors manage their own product catalogues and inventory; buyers can search across all vendors. We need Stripe Connect for split payments, a React storefront, and a REST API. Expected scale: 50 vendors and 10k orders/month at launch, growing to 500 vendors within 18 months. We must be GDPR-compliant and the API must support white-label access for resellers.

Why it works: covers the system type, users (vendors + buyers), integrations (Stripe), tech preference (React), scale (quantified), and constraints (GDPR, white-label).

What to include

CategoryExamples
System typeSaaS platform, mobile app + API, internal tool, data pipeline
UsersRole names, estimated count, technical sophistication
Core featuresThe 3–5 things the system must do on day one
ScaleConcurrent users, requests/second, data volume, geographic regions
IntegrationsStripe, Auth0, Twilio, existing internal APIs
Tech preferencesIf you have a preferred language, framework, or cloud provider
ConstraintsCompliance (GDPR, HIPAA, SOC 2), budget ceiling, launch deadline

What to avoid

  • Vague scope: “a platform for managing things” → say what things and who manages them
  • Solution-first descriptions: “I need a React app with Redux and a Node.js backend” → describe the problem, not the stack; the Tech Leader will choose the right tools
  • Listing every feature: prioritise; the Architect will ask about lower-priority features during the conversation
  • Contradictions: “simple MVP” + “enterprise-grade multi-region failover” — pick the right level and be explicit

Refining in the chat

After your initial message, the Architect will ask clarifying questions. Good answers:

  • Give numbers not adjectives: “~500 concurrent users” not “lots of users”
  • Distinguish MVP from future: “For v1 we only need email auth; OAuth is a future milestone”
  • Mention non-negotiables explicitly: “The database must be on-premises — no cloud SQL”

You can also edit any past message by hovering it and clicking the pencil icon. This branches the conversation — useful for exploring “what if we went serverless instead?”.

Using file attachments

The New Project modal and the Architect chat both accept file attachments. Files are stored as persistent context for the Architect throughout the conversation.

File typeWhen to use
Wireframes / mockupsUI intent, page structure, navigation flow
Existing API specs (OpenAPI, Postman)Integration contracts the new system must honour
ERD / data model diagramsIf you have a domain model the architecture must follow
Competitor screenshots”The UX should work like this”
Technical requirements documentsCompliance or security specs from your organisation

Next steps