feat: improve agentic AI development flow and guidelines#1411
feat: improve agentic AI development flow and guidelines#1411jescalada wants to merge 11 commits intofinos:mainfrom
Conversation
✅ Deploy Preview for endearing-brigadeiros-63f9d0 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1411 +/- ##
=======================================
Coverage 89.66% 89.66%
=======================================
Files 68 68
Lines 4869 4869
Branches 888 888
=======================================
Hits 4366 4366
Misses 485 485
Partials 18 18 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
dcoric
left a comment
dcoric
left a comment
There was a problem hiding this comment.
Nice improvement! This should help steer AI-assisted code changes toward consistent repo rules. I left a couple of small nits.
One additional improvement: make the setup cross-tool friendly by using a canonical policy file + thin bridge files.
Proposal:
- Use
AGENTS.mdas the canonical repo policy. - In
AGENTS.md, add a rule like: “For command workflows, read.claude/commands/*.md.” - Add thin tool-specific bridge files:
CLAUDE.md-> points toAGENTS.md+.claude/commandsGEMINI.md-> points toAGENTS.md(or mirrors the key rules).cursor/rules/00-agents.mdc(or.md) -> points toAGENTS.md
Notes / compatibility:
- Codex: uses
AGENTS.md. - Cursor: uses
AGENTS.md/CLAUDE.mdand.cursor/rules(commands via.cursor/commands). - Gemini CLI: defaults to
GEMINI.md, but can be configured to readAGENTS.mdviacontext.fileName. - Claude Code: custom slash commands live in
.claude/commands.
Refs:
- Claude Code slash commands: https://docs.claude.com/en/docs/claude-code/slash-commands
- Cursor rules: https://docs.cursor.com/context/rules-for-ai
- Cursor commands: https://docs.cursor.com/en/agent/chat/commands
- Cursor CLI: https://docs.cursor.com/en/cli/using
- Gemini
GEMINI.md: https://geminicli.com/docs/cli/gemini-md - Gemini config: https://geminicli.com/docs/get-started/configuration/
- Codex +
AGENTS.md: https://openai.com/index/introducing-codex/
For a real-world OSS example of this pattern, see:
https://github.com/ghostty-org/ghostty
It demonstrates a clean canonical policy file with tool-specific bridges, which aligns well with this proposal.
| - Never modify code without programmer approval | ||
| - Show exact reply text before queuing it | ||
| - The programmer can modify any reply at any point | ||
| - Always checkout with `--detach` to avoid creating local branches |
There was a problem hiding this comment.
This conflicts with git push rule from line 46 in this file. Pushing detached HEAD will fail with regular git push as instructed. I think this should be limited for a review purposes, or extend git push to use git push <remote> HEAD:<pr-head-branch> which will work with --detach
There was a problem hiding this comment.
Interestingly, ghostty isn't using bridges at all (they only seem to have an .agents directory that contains both commands and skills.
I updated the PR so that our setup looks like theirs!
There was a problem hiding this comment.
(Meant to reply to your PR comment!)
There was a problem hiding this comment.
Also, I just fixed the issue you mentioned by adding the following rule near the bottom:
- Never push while in detached state. Before any push, explicitly checkout the target branch after programmer confirmationThis should theoretically exit detached state and get on an actual branch. We should test to see if the more detailed git push would work better instead.
|
|
||
| 1. Save the current branch name: `git rev-parse --abbrev-ref HEAD` | ||
| 2. Checkout the PR branch: `gh pr checkout <number> --detach` | ||
| 3. Fetch all review comments: |
There was a problem hiding this comment.
Just a suggestion as REST endpoint does not return resolved status on comments, it just lists them, there is alternative to use gh command with GraphQL:
gh api graphql -f query='
query($owner:String!, $repo:String!, $number:Int!, $cursor:String) {
repository(owner:$owner, name:$repo) {
pullRequest(number:$number) {
reviewThreads(first:100, after:$cursor) {
pageInfo { hasNextPage endCursor }
nodes {
isResolved
isOutdated
path
line
originalLine
comments(first:100) {
nodes {
databaseId
body
author { login }
createdAt
url
}
}
}
}
}
}
}' -F owner={owner} -F repo={repo} -F number=<number> -F cursor=<cursor>
That gives unresolved review threads with the latest comment details;
This avoids double tool-calling
3 participants
Closes #1410.
Note: This PR summary was generated via the
/summarycommand and manually tweaked.What: Add
CLAUDE.mdand a set of Cursor/Claude commands under.claude/commandsto support AI-assisted development and consistent agent workflows.Why: Agents need proper context for GitProxy’s architecture and conventions. Furthermore, the new commands help speed up typical tasks such as issue creation, PR summaries, docs updates, linting, and review follow-up to improve the dev experience and help humans focus on quality control and more pressing issues.
Changes:
CLAUDE.mdwith project overview, build/run steps, high-level architecture (proxy, service, config, UI), development guidelines, and agent workflow (delegation)..claude/commands/with seven commands:address-review(apply review feedback)commit(incremental conventional commits)docs(update README/Architecture/CLAUDE from branch changes)implement(issue → branch → code → commit → summary)issue(summarize issue for implementation)lint(run lint/format)summary(PR description summary)..gitignoreto ignore/plans(where command outputs are stored).README.mdContributing section to point toCLAUDE.mdand.claude/commandsfor AI-assisted development.How to verify:
CLAUDE.mdand confirm it describes proxy, service, config, UI, and push/pull/default chains./summary,/docs) and confirm they behave as described in their files.plans/is ignored by Git and thatREADME.mdlinks toCLAUDE.mdand.claude/commands.Credit goes to @sudiptob2 for original implementation in Armada Spark!