Recommendations for AI app building

Table of contents

• Overview
• Be aware of security implications
• Select the right AI models and tools
  • Select the right AI mode
• Provide AI with the right context
  • Clear prompting
  • Repository context
• MCP server configuration
• Validate AI outputs
• Commit and test philosophy
• Strategies for AI-assisted development
  • Test-driven development and outline strategy
    • How this strategy works
    • When to use this strategy
    • Examples
  • Manual exploration strategy
    • How this strategy works
    • When to use this strategy
    • Examples

Overview

This section provides tool-agnostic guidelines for developing Contentful applications using AI-assisted tools that adapts to different development workflows.

Our approach to AI-assisted development follows the human-in-the-loop principle, which emphasizes that AI tools augment and enhance human capabilities rather than replace human judgment and expertise. The key principles for this approach are:

1. Human oversight — AI assists development, but humans make all final decisions.
2. Code review — Always review and validate AI-generated code before using it.
3. Learn and adapt — Use AI as a learning tool to improve skills.
4. Context matters — Provide business context that AI tools lack.

Be aware of security implications

AI tools can accelerate development, but they can also introduce security risks if you do not validate their output. The items below summarize key security concerns to consider when you rely on AI-generated code in your projects.

1. Vulnerabilities — AI-generated code may contain vulnerabilities or insecure patterns. Always review and test thoroughly.
2. Sensitive information — Be cautious about sharing sensitive information, API keys, or proprietary code with AI tools.
3. Outdated packages — Verify that AI-suggested packages are up-to-date and free from known vulnerabilities.
4. Authentication flows — Ensure AI-generated authentication follows security best practices.
5. Compliance: Validate tools and generated code and confirm that it meets security and compliance requirements.

Select the right AI models and tools

Be proactive when selecting AI models and tools. Most AI development agents include an auto-select model feature that chooses a suitable model for general use. If you need more control or specialized capabilities, manually select a model that aligns with your coding or requirements. Because different models excel in different areas, thoughtful selection improves productivity, efficiency, and solution quality.

Select the right AI mode

We recommend checking which modes are available in your AI agent at implementation time and selecting the one that best fits your task. Each mode offers different strengths, so choosing the most suitable one helps the agent work more accurately and efficiently.

Provide AI with the right context

Provide clear context to receive accurate and useful results from an AI assistant. By combining clear prompting, comprehensive repository context, and the right tool configuration, you enable the AI assistant to act as an effective development partner—improving accuracy, reducing duplication, and strengthening your overall foundation for development.

Clear prompting

Be specific with your instructions to your AI agent. Generic prompts often lead to vague results because the assistant fills in gaps by making assumptions. Include details about functionality, expected format, and constraints. Provide examples when possible.

You can also use meta prompting, a technique where you ask the AI to generate the optimal prompt for a specific coding or engineering task. For example, instead of prompting:

Write a TypeScript function to validate user input

You could ask:

Write an effective prompt that would instruct an AI to generate clean, type-safe TypeScript code for validating user input, handling edge cases, and including basic unit tests.

This technique helps clarify intent, define constraints like performance, typing, or code style, and leverage the model’s understanding of effective prompt design.

Repository context

When building a new app, download the Contentful Apps repository, add your app there and give your AI assistant access to all apps in the repository. This enables component reuse and supports consistency across applications. Reinforce this by adding rules that prioritize reuse and alignment with existing patterns. This ensures AI to follow established best practices from other projects.

MCP server configuration

You can connect your AI assistant to an MCP (Model Context Protocol) servers. MCP servers extend the assistant’s functionality by proving structured access to external systems, APIs, or project data. Configure your environment so the assistant can securely interact with relevant APIs, databases, or development utilities. Enable only the tools needed for your current workspace to minimize noise and improve reliability.

For example, connecting to the Contentful MCP server lets the assistant interact with your Contentful space to read entries, manage content types, and validate schema changes.

Validate AI outputs

Review every AI suggestion thoroughly to ensure you understand what you are building. Without this understanding, maintaining, debugging, and extending the solution becomes difficult. AI cannot fill knowledge gaps, and even if code appears correct, you might not know why it works.

AI is most effective when you understand the problem, the solution, and the patterns you can generalize. Build this knowledge by studying the problem and strengthening your technical skills instead of treating AI as a black box.

Work in small increments rather than writing large prompts that generate code across multiple files. This keeps the process focused, reduces reviewer fatigue, and makes reviews easier to manage.

Commit and test philosophy

Commit changes whenever you reach a stable working point. Many AI assistants provide restore points that help roll back experiments. Consider adhering to the following best practices:

• Revert early — Catch errors early by reverting or redirecting when AI diverges from expectations.
• Write tests promptly — Write or finalize tests as soon as functionality is stable. When confidence is high, ask AI to generate tests before implementation.
• Document while fresh — Add documentation or comments while the context is fresh to maintain clarity throughout the development process.

Strategies for AI-assisted development

This article presents two strategies for AI-assisted development: test-driven development (TDD) with an outline strategy, and manual exploration.

Test-driven development and outline strategy

Use this strategy when the problem and solution are well defined, and you want AI to write implementations guided by tests. In this approach, you create tests first to define the expected outcome, then ask the AI agent to implement code that passes those tests.

How this strategy works

1. Ask the AI agent to create tests based on your expected outcome. Confirm that the tests fail.
   Note: Add an explicit rule in your prompt that you are using test-driven development to prevent the AI from creating mocks.
2. Review the tests and refactor them if they do not match your needs.
3. Commit the tests.
4. Ask the AI agent to write code that makes the tests pass.
5. Review and refactor the code as needed.
6. Commit the changes.

When to use this strategy

• Clear problem — You have a clear understanding of the problem at hand.
• High-confidence solution — You can confidently break the system into functions, interfaces, or flows.
• Test-first iteration — You want AI to generate implementations and iterate on failing tests.

Examples

• Configuration page — You are a React expert and ask AI to generate a configuration page with an input and a dropdown.
• CRUD endpoint — You are experienced in backend development and ask AI to create a generic CRUD endpoint.

Manual exploration strategy

Use this strategy when the problem is unclear or involves unfamiliar tools, and you need to explore before moving into structured development. In this approach, you explore the problem manually before planning a solution and committing the results.

How this strategy works

We recommend using Plan Mode for this strategy if it is available in your agent.

1. Ask the AI agent to read relevant information about the issue you want to resolve. Use non-coding modes to ensure it only gathers context.
2. Create a plan with the AI agent to approach the issue.
3. Verify that the AI agent does not make incorrect assumptions.
4. Refine the plan before implementation:
   Refine the plan early to gain higher leverage, as improving the plan itself is more effective than revising generated code later.
5. Ask the AI agent to implement the solution.
6. Review and refactor the code as needed.
7. Iterate the last two steps as required.
8. Commit the changes.

When to use this strategy

• Uncertainty — The problem involves ambiguity or unknown implementations.
• Unfamiliar tools — You are working with tools, protocols, or behavior that are unfamiliar.
• Undefined success — You have not yet established a clear definition of success in your project.

This approach allows you to study the problem, reduce uncertainty, and build foundational understanding. Once you establish clarity, you can provide the AI agent with more specific rules or prompts.

Examples

• OAuth exploration — You need to learn how OAuth works, so you manually implement client IDs, secrets, tokens, and distinguish between authorization and authentication.
• Asynchronous workflow — You are handling a complex asynchronous workflow involving multiple systems. You first build a simple end-to-end thread manually, with AI support, and later introduce more automation.