Find all idempotent matrices such that $(A-B)^2 = 0$
We can see that the hypotheses imply that $A+B=AB+BA$, and if we multiply by $AB$ on the right, we get $AB+BAB=(AB)^2+BAB$, which also implies that $AB$ is idempotent (and we can also see that $BA$ is idempotent).
After that, I am not sure what to do next.
I add a necessary condition that $\operatorname{rank} (A) = \operatorname{rank} (B)$, since $A-B$ is nilpotent, then $\operatorname{Trace} (A-B) = 0$, so $\operatorname{Trace} (A) = \operatorname{Trace} (B)$. But $A$ and $B$ are projectors, so $\operatorname{rank} (A) = \operatorname{rank} (B)$.
additional sufficient condition: if $\text{im}(A) = \text{im}(B)$, then $AB=B$ and $BA=A$. This implies that $A+B=AB+BA$, which further implies that $(A-B)^2=0$.
Best Answer
Let $N=B-A$. Then $N^2=0$ and from $A+N=(A+N)^2$, we obtain $AN+NA=N$. By a change of basis, we may assume that $A=\pmatrix{I_r&0\\ 0&0}$. Let $N=\pmatrix{X_{r\times r}&Y_{r\times(n-r)}\\ Z_{(n-r)\times r}&W_{(n-r)\times(n-r)}}$. The two conditions $AN+NA=N$ and $N^2=0$ imply that $X,W,YZ$ and $ZY$ are zero. That is, the general solution is given by $$ A=P\pmatrix{I_r&0\\ 0&0}P^{-1} \quad\text{and}\quad B=P\pmatrix{I_r&Y\\ Z&0}P^{-1} $$ for some $r\in\{0,1,\ldots,n\}$ and for some matrices $Y,Z$ and $P$ such that $YZ=0$ and $ZY=0$.
If you want the roles of $A$ and $B$ to look more symmetric, observe that $$ \begin{aligned} \pmatrix{I&Y\\ 0&I}\pmatrix{I&0\\ 0&0}\pmatrix{I&-Y\\ 0&I} &=\pmatrix{I&-Y\\ 0&0},\\ \pmatrix{I&Y\\ 0&I}\pmatrix{I&Y\\ Z&0}\pmatrix{I&-Y\\ 0&I} &=\pmatrix{I&0\\ Z&0}. \end{aligned} $$ So, by negating $Y$, the general solution can also be expressed as $$ A=P\pmatrix{I_r&Y\\ 0&0}P^{-1} \quad\text{and}\quad B=P\pmatrix{I_r&0\\ Z&0}P^{-1} $$ with $YZ=0$ and $ZY=0$.