Add AI policy derived from HA

[sveinse]

Given the increasing amount of AI generated code in this project, its prudent that we get some guidelines established. That is not to say that we shouldn't be using AI/LLMs, but some boundaries are needed. Since this Zaptec integration is specifically built for HA, I believe its beneficial for us to use and mirror the policies from the Open Home Foundation (the org behind Home Assistant).

This PR introduces an AI policy and creates an AGENTS.md file to assist AI assisted development.

I have edited and reviewed these based on what I consider fair, but I'm very open to feedback, discussions and adjustments. Since this is fairly important for all of us I'm really grateful for any opinions we can get.

@steinmn and @rhammen I'd like your take on this PR please.

[steinmn]

Fully agree on aligning with the policies from HA.

While I haven't gotten very deep into using agentic AI yet, this all seems perfectly reasonable to me.

[sveinse]

One of the practical challenges I see right now with the AI assisted PRs is the amount of text being generated. Exactly because they are AI assisted, it is very important that we review the commits proper. Hallucination is a real thing. But the work for my part is going very slow, since the PRs are big and with a lot of text to digest.

[rhammen]

@sveinse @steinmn
I see that I am rather late, possibly too late, to give my view since the PR just got merged.
I do however want to share my view; I just wanted/needed to give it a bit more thought...
(and write it in my own words 😃)
So sorry for the delay in replying.

I understand and support that we want to set some guidelines/boundaries to the usage of AI.
Using the HA AI policy as a starting point is then a logical starting point.
I agree that we don't want fully automated AI submitting things, and that there should always be 'a human in the loop'.

However....
In the current wording, the policy puts a quite high bar to the usage of AI:
"You should be able to explain every change in a pull request you submit." and similar sentences.

The concern I have with this high bar is the following: it asks of the submitter to be as smart/knowledgeable as the AI, with respect to the proposed code changes. Depending on the human and the AI model, this is not trivial request, and this will only get more challenging in the near future.
If we really want that, I think we are back to square one, let me explain.

What I have seen with the custom component where I - since a year - am the main developer, the Luxtronik heatpump controller, and with this Zaptec custom component, is that it is/was basically a one-man-show. Progress on developments, fixing issues, implementing feature requests depend on the time one or two people can/want to spend. And if that time is (very) limited, then the progress stalls, and you get to a list of 30+ issues/feature request with a very low implementation rate...
Other users of custom components 'just' enter new issues or feature request, but don't (or hardly) contribute themselves.
They are often not knowledgeable enough to make the changes themselves, or they don't trust themselves submitting PRs.
I think AI can change that, and in the (near?) future will change that... IF we are willing to accept it...

I contribute to the luxtronik heatpump custom component, and I am also willing to do that to this Zaptec custom component since I installed a Zaptec charger at my home in June this year. But I do this with significant help of AI, as you have seen, and I want to (and have been) transparent about that.
I use AI because it allows me to learn new AI-usage skills, and brings improvements to the custom components much faster than without AI, and that is in my view a big (game-changing) benefit for the custom components.

Do I understand every single line of code the AI proposes? No, I am not a native SW developer, and I will not be one.
I am however an engineer with a master of science in physics, with 25+ years of work experience, and I am able to reason and discuss with the AI and with you, the maintainers, about the bigger picture of the changes/PRs I submit. Expecting contributors to do this and not rely only on AI is a fair request.

Will the AI make mistakes in the process: yes, see #410...
Will I make mistakes in the process, and miss some things I should have captured: yes, see #410 ...
But also human contributors will make mistakes when contributing.
Overall, I strongly believe that the overall gain for the Zaptec integration of getting the large issue list reduced, code quality improved and long awaited features implemented is worth accepting that with AI usage some mistakes will happen.

My proposal would be to relax the AI policy a bit, in line with my reasoning above.
Then we try this AI supported process for a while, and we will learn along the way how this works out in practice.
And if needed, we can always adapt the AI policy at any point in time.

Happy to learn your view on this.

Remco

[steinmn]

I think Frenck (HA lead engineer) summed it up quite nicely here: https://frenck.dev/open-source-was-not-ready-for-ai-speed-contributions/

Reviewing contributions takes time and effort, and is now quickly becoming the most significant bottleneck as Frenck points out. That's why I think it's important to have contributors pre-review their contributions as much as they can before submitting. Even if it is just reading through the changes and asking the AI "what does this do, is it necessary?" for any change they don't understand. Sure, the explanation might not always be correct, but at least a human has evaluated if the explanation made sense. This might be an overly lenient interpretation of "You should be able to explain every change in a pull request you submit." according to some, but I still think it can reduce the load on the reviewers while allowing less experienced developers to contribute.

Overall, I strongly believe that the overall gain for the Zaptec integration of getting the large issue list reduced, code quality improved and long awaited features implemented is worth accepting that with AI usage some mistakes will happen.

I rely on this integration to make sure my car is charged enough in the morning to get to work and home again without going over power limits that will increase the electricity tariffs too much, so robust and reliable is far more important than feature-rich to me. Adopting a "move fast and break things"-attitude is not really an option to me.

If you have any specific changes you would like to add to the policy to relax it, I think it might be easier to discuss if you just open a PR with those changes. With the dream goal of someday having the integration merged into core in mind, staying aligned with the HA policy still seems like the better approach to me.

[Hellowlol]

For what it’s worth I expect all contributors to be able to explain the intent behind they code they contribute. If you can’t how can you realistically know what it does? It just a huge time waist for the maintainers.SteffenSendt fra min iPhone26. juli 2026 kl. 16:35 skrev steinmn ***@***.***>:steinmn left a comment (custom-components/zaptec#408) I think Frenck (HA lead engineer) summed it up quite nicely here: https://frenck.dev/open-source-was-not-ready-for-ai-speed-contributions/ Reviewing contributions takes time and effort, and is now quickly becoming the most significant bottleneck as Frenck points out. That's why I think it's important to have contributors pre-review their contributions as much as they can before submitting. Even if it is just reading through the changes and asking the AI "what does this do, is it necessary?" for any change they don't understand. Sure, the explanation might not always be correct, but at least a human has evaluated if the explanation made sense. This might be an overly lenient interpretation of "You should be able to explain every change in a pull request you submit." according to some, but I still think it can reduce the load on the reviewers while allowing less experienced developers to contribute. Overall, I strongly believe that the overall gain for the Zaptec integration of getting the large issue list reduced, code quality improved and long awaited features implemented is worth accepting that with AI usage some mistakes will happen. I rely on this integration to make sure my car is charged enough in the morning to get to work and home again without going over power limits that will increase the electricity tariffs too much, so robust and reliable is far more important than feature-rich to me. Adopting a "move fast and break things"-attitude is not really an option to me. If you have any specific changes you would like to add to the policy to relax it, I think it might be easier to discuss if you just open a PR with those changes. With the dream goal of someday having the integration merged into core in mind, staying aligned with the HA policy still seems like the better approach to me. —Reply to this email directly, view it on GitHub, or unsubscribe.Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today! You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[sveinse]

@rhammen
Initiative and contributions are very welcome. This community is not big - we are only a very small set of active devs. Development is often motivated and driven by specific need. E.g. "this doesn't work for me" or "I'm missing this". What you so far have been doing is taking a real stab at our backlog of issues with the intent to increase the overall quality, which is fantastic.

The intent with the policy is never about reducing the opportunity to use AI. Rather the opposite. I use AI tools a lot, even in this project. It's helpful, it saves me a ton of time and sometime even teach me things I didn't know. However, I always stay on top of what it does. I'm always accountable for the code it writes. If it screws up, its on me. I can never say "it was the AIs fault".

Development follow the flow where a developer does some thinking, writes some code and prepares to argue why the PR should be included into the project. A champion. The role of the reviewer is to give feedback and approve that this fits the purpose and intent of the repo. Without a champion, which is the case with purely AI generated PRs, there no real person to argue why this fix makes sense. The responsibility for the content of the PR then rides on the reviewers which are already very busy. Having an AI policy is a tool to help us how to responsibly use AI tools with this project, not to quench AI assisted initiative.

I hope this was clarifying.