From f3681129033995114719fd238286eb31c5633451 Mon Sep 17 00:00:00 2001 From: Mateusz Ostafil Date: Tue, 25 Feb 2025 13:38:11 +0100 Subject: [PATCH 1/3] docs: add notes for ai contexts doc --- .../guides/6.best-practices/3.ai-contexts.md | 69 +++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 docs/content/guides/6.best-practices/3.ai-contexts.md diff --git a/docs/content/guides/6.best-practices/3.ai-contexts.md b/docs/content/guides/6.best-practices/3.ai-contexts.md new file mode 100644 index 0000000000..c4ae703e9c --- /dev/null +++ b/docs/content/guides/6.best-practices/3.ai-contexts.md @@ -0,0 +1,69 @@ +# Coding with AI + +Alokai aims to boost developer productivity in many ways. E.g. by giving you storefront accelerator and OOTB integrations with 3rd party services. +Now we want to go even further by boosting your productivity with AI. + +## Disclaimer + +AI field is evolving rapidly. New models, new tools, new workflows are emerging every day. +While we do our best to keep this guide updated, we might miss some things. +Revisit this guide regularly and don't follow it blindly. + +## AI Contexts + +Alokai provides a set of AI contexts that can be used to code with AI. +//TODO: explain what are AI contexts + +## Expectations Management + +//TODO: elaborate on this points + +- AI is not a replacement for your knowledge and experience. +- AI is a tool to help you code faster and more efficiently. +- AI is not a replacement for your ability to reason and think. +- AI is just predicts what would be the most likely outcome for the given input. +There's also some randomness added to the process, so the results might be inconcistent. +- AI can make silly mistakes. But it can do amazing things at the same time. Don't get disappointed too fast. +- Don’t extrapolate your vision of intelligence on AI. AI is a different form of intelligence than human intelligence. +It can make silly mistakes. But it can do amazing things at the same time. Don't get disappointed too fast. +- Be flexible with your expectations of the output. +- AI cannot see the results of the code yet. + +## Recommended tools + +### IDEs + +- [Cursor](https://www.cursor.com/) +- [Windsurf](https://windsurf.dev/) + +GitHub Copilot is not recommended. Agent mode is coming soon but we have not tested it yet. + +Alternatives to consider: + +- [Cline](https://cline.bot/) + +### LLM models + +- Claude + +## Workflows + +//TODO: elaborate on this points + +- hands on - you tell the AI what to do +- hands off - you provide the AI with enough context so it can decide what to do + +## General recommendations + +//TODO: elaborate on this points + +- review the code to know what's going on +- keep files small +- edit the context when needed +- when something goes wrong retry or revert +- ask AI to check the codebase for examples +- copy and paste error messages +- experiment +- don't hesitate to get your hands dirty - sometimes it's faster to do things manually than to explain it to AI +- ask AI to review its own code + From baa623a132898b15dc461991dab37df53cc8a1d6 Mon Sep 17 00:00:00 2001 From: Mateusz Ostafil Date: Thu, 6 Mar 2025 10:54:19 +0100 Subject: [PATCH 2/3] add: ask ai to read the docs to the best practices --- docs/content/guides/6.best-practices/3.ai-contexts.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/content/guides/6.best-practices/3.ai-contexts.md b/docs/content/guides/6.best-practices/3.ai-contexts.md index c4ae703e9c..5f7fbf5745 100644 --- a/docs/content/guides/6.best-practices/3.ai-contexts.md +++ b/docs/content/guides/6.best-practices/3.ai-contexts.md @@ -28,6 +28,7 @@ There's also some randomness added to the process, so the results might be incon It can make silly mistakes. But it can do amazing things at the same time. Don't get disappointed too fast. - Be flexible with your expectations of the output. - AI cannot see the results of the code yet. +- AI can forget things. ## Recommended tools @@ -66,4 +67,4 @@ Alternatives to consider: - experiment - don't hesitate to get your hands dirty - sometimes it's faster to do things manually than to explain it to AI - ask AI to review its own code - +- ask AI to read the docs From ec7a4be6f123bbba8376200ae3902eb5677b0d79 Mon Sep 17 00:00:00 2001 From: Mateusz Ostafil Date: Wed, 19 Mar 2025 14:37:00 +0100 Subject: [PATCH 3/3] docs: add some recommendations --- docs/content/guides/6.best-practices/3.ai-contexts.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/content/guides/6.best-practices/3.ai-contexts.md b/docs/content/guides/6.best-practices/3.ai-contexts.md index 5f7fbf5745..7ee3ac2ad8 100644 --- a/docs/content/guides/6.best-practices/3.ai-contexts.md +++ b/docs/content/guides/6.best-practices/3.ai-contexts.md @@ -61,7 +61,8 @@ Alternatives to consider: - review the code to know what's going on - keep files small - edit the context when needed -- when something goes wrong retry or revert +- when AI goes wrong, ask it why it dit it this way +- don't hesitate to start over again - ask AI to check the codebase for examples - copy and paste error messages - experiment