Docs: Coding with AI best practices #7406
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,71 @@ | ||
| # 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 was a problem hiding this comment. You could just remove this line and the meaning would be the same. What may be non-obvious is context that is being attached and effective communication. The "empathy" element that I was talking about on our last call. Just like you'd need to explain some things to another dev, you have to transfer this knowledge to the AI. |
||
| 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. | ||
|
There was a problem hiding this comment. AI doesn't work the same way like human intelligence does. Some things that are easy to humans, are hard for AI, while some things that are hard for humans, are easy for AI. I think we could also give examples of AI failing to do arithmetics or count "r" in strawberry. |
||
| 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. | ||
|
There was a problem hiding this comment. Not by default, also we should probably double-check this thing about allowing AI to see "the browser", you can also copy-paste terminal. So maybe more accurate would be "AI does not see the results of the code by default" |
||
| - AI can forget things. | ||
|
|
||
| ## 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. | ||
|
There was a problem hiding this comment. GitHub Copilot is not recommended, but we do provide a context for it attached ootb. Just because copilot is poor, doesn't mean we can allow ourselves to completely ignore it. It is the most known tool in this domain. There was a problem hiding this comment. Also, we should explain why agent mode is a big deal |
||
|
|
||
| Alternatives to consider: | ||
|
|
||
| - [Cline](https://cline.bot/) | ||
|
|
||
| ### LLM models | ||
|
|
||
| - Claude | ||
|
Comment on lines
+46
to
+48
There was a problem hiding this comment. I mean, we don't support specific LLM model, it's the job of IDE to provide models. Just because we most extensively tested claude, doesn't mean we target claude exclusively. I'm not even sure you can switch context depending on the model. |
||
|
|
||
| ## Workflows | ||
|
There was a problem hiding this comment. Styles of work? Workflow feels... a bit automated? Like CI/CD |
||
|
|
||
| //TODO: elaborate on this points | ||
|
There was a problem hiding this comment. We should state that they're not mutually exclusive and that you can do it both ways |
||
|
|
||
| - 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 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 | ||
|
There was a problem hiding this comment. when the AI goes against conventions |
||
| - 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 | ||
| - ask AI to read the docs | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe I'd add that AI is made to work with it iteratively. I know people who think that it's one-off tool. You give it a task and if it failed, then they think AI is incapable of performing the task.