Struggling to Explain AI-Written Code? Try Sphinx Before You Push
Sphinx pauses your push to ask: if a worker finishes a job and crashes before acknowledging it, does the job run twice? What happens when your answer is wrong?
- Use Sphinx’s pre-push questions to practice explaining code produced with an agent.
- A separate reviewer reads committed changes and related code, then follows incorrect answers with explanations.
- The exercise is open-book. A completion record does not establish code correctness or replace tests.
Predict what the change will do
parthh01/sphinx adds an understanding check to agent-assisted development. A matching push waits while a separate reviewer asks about the committed change. That reviewer does not receive the conversation that produced the code.
The project illustrates the idea with a queue worker that completes an operation but crashes before acknowledging the job. The developer must explain whether redelivery can repeat the operation. That is a sample scenario, not a fixed question asked of every repository.
Incorrect answers lead to explanations and follow-up questions. The exercise is open-book. According to the architecture document, the reviewer follows relevant source and tests to support its questions. Completion records are tied to the assessed change, destination, and policy, then revalidated.
Global hooks and repository policy have different jobs
Installation sets the user’s global Git core.hooksPath. It can therefore affect repositories beyond the one currently open. Existing hooks run first, and the initial branch defaults target pushes to main or master.
The repository policy controls events, branches, remotes, and question depth. Push policies match the destination branch, not simply the name of your checked-out branch. Choosing which operations wait is a separate decision from choosing how detailed the questions should be.
A local questionnaire can still send code to a provider
The reviewer provider receives changed code, related files, answers, and project context. For push checks, code evidence comes from Git commits rather than uncommitted working files.
Default exclusions cover environment files, private keys, and common credential files. Additional sensitive paths belong in .sphinxignore. These are path filters: they do not detect a secret pasted into an otherwise included source file.
There is no default cap on model calls. You can set one, but a request limit is not a spending limit. Adoption therefore involves deciding which evidence may be sent and whose model allowance or account pays for the review.
A GitHub stamp records the exercise, not code correctness
Sphinx presents itself as practice. Someone with local access can bypass hooks or obtain help, and the examiner can make mistakes. Passing does not establish that the change is bug-free.
| Mechanism | What it establishes |
|---|---|
| Local completion | The understanding checkpoint for that change was completed. |
| A commit status or Sphinx check | The local completion record is visible on GitHub. |
| A required check with branch protection | A completion record can be made a merge condition; it remains self-reported. |
The detailed configuration guide describes requiring the Action’s check through branch protection. It also says that the result is reported by the pusher’s machine, rather than being cryptographic proof of understanding.
The useful addition is a deliberate moment for developers to explain their changes. A team can place that exercise alongside review and testing without treating its passing stamp as a substitute for either.
Frequently asked questions
Can a team require the GitHub check?
The configuration guide describes an Action requirement and branch-protection setup. The recorded result is still reported by the contributor’s machine.
Can I read the code while answering?
Yes. The exercise permits consulting the code while explaining behavior and failure cases.