Skip to content

add concise project guidance for coding assistants - #408

Open
atsju wants to merge 1 commit into
masterfrom
JST/agent-guide
Open

atsju wants to merge 1 commit into
masterfrom
JST/agent-guide

Conversation

@atsju

@atsju atsju commented Nov 5, 2026

Copy link
Copy Markdown
Collaborator

Close #405.

@atsju
atsju requested review from githubdoe and gr5 November 5, 2026 12:42
@github-actions

github-actions Bot commented Nov 5, 2026

Copy link
Copy Markdown

🚀 New build available for commit 39b7106
Download installer here

@gr5

gr5 commented Nov 5, 2026

Copy link
Copy Markdown
Collaborator

This is way outside my expertise. I think @Lucassifoni should be brutaly honest about what is good and bad about this.

I also think that maybe an AI should come up with this as it will mostly be read by other AIs and my understanding is that they know how to talk to each other better than we do. Then after the AI comes up with it we go over it and make corrections if it got something wrong.

@Lucassifoni

Copy link
Copy Markdown
Contributor

Would you maybe be interested in a recording of coming up with a small fix plan, then executing it with the help of an agent ? I mean in the context of DFTFringe.

@atsju

atsju commented Nov 5, 2026

Copy link
Copy Markdown
Collaborator Author

TBH I don't think this agent files changes the world. It's very minimalistic but will help an agent know how to build/test. It should be much more developped but as we don't have same process I didn't want to describe how to build, test, ...
At least now an agent would now the important files to look at first.

I agree with Lucas, do you want to see our development workflow with agents ? How we do a plan, and then fix, test, ...

@gr5

gr5 commented Nov 6, 2026

Copy link
Copy Markdown
Collaborator

Would you maybe be interested in a recording of coming up with a small fix plan, then executing it with the help of an agent ? I mean in the context of DFTFringe.

Are you asking if I'd like you to create a screen recording of you fixing some small thing in DFTFringe? That would be pretty cool. An example might be bug #318 . I think the fix is probably simple but possibly difficult for me to figure it out. I can supply you with 4 wavefront files if you want. Actually you can just supply any old wavefront random wavefront files if you want and tell DFTFringe that they are rotated at made up rotations, but you need pairs that are 90 degrees apart.

I checked and the current code in master still has the problem shown in issue #318

@gr5

gr5 commented Nov 6, 2026

Copy link
Copy Markdown
Collaborator

It's okay if the video is slow and "boring" as I can always fast forward through parts where nothing much is happening and I can go back over the confusing parts later.

@Lucassifoni

Copy link
Copy Markdown
Contributor

My live spoken english is slow and boring so it should be quite easy to follow. I'll try to do that tomorrow !

@atsju

atsju commented Nov 7, 2026

Copy link
Copy Markdown
Collaborator Author

I did a first video. It's basically an introduction to Github Copilot usage in VScode.
https://youtu.be/P6BduHBIpa0

I will try to do a second video tomorrow to see how AI fixes bug.

I'm also very interested in your video Lucas; I never used Claude interface.

@atsju

atsju commented Nov 8, 2026

Copy link
Copy Markdown
Collaborator Author

Here is the second video
https://youtu.be/gXZGbVMJdpo

@atsju

atsju commented Nov 8, 2026

Copy link
Copy Markdown
Collaborator Author

By the way, I want to mentions that the evolutions of AI in last 6, 12 and 18 month has been exponential. The video could be almost obsolete in 6 to 12month from now.
I also need to mention I'm absolutely not AI expert user as I do not develop much anymore. Lucas probably uses it much more efficiently.

@gr5

gr5 commented Nov 8, 2026

Copy link
Copy Markdown
Collaborator

I watched the first video. It's helpful to me as I'm extremely new to agentic programming.

Unfortunately audio drops out at about 16 minutes into the first video. I'll watch second video next.

@Lucassifoni

Lucassifoni commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

I've filmed one, but I'm sorry, it is 55 minutes long ... here it is. I still don't know anything about QT nor C++, which is why I chose to give very vague initial instructions then gain precision about my actual goal for the demo, having end-to-end tests for DFTFringe that will someday run in CI so we put less manual QA pressure on the current maintainers.

It mixes me learning about QT/C++ testing and moving towards that goal with the agent, but I think it shows quite well how it can be steered and nudged towards a goal. All the "trivia" that I add is to imprint the context with the fact that while I can understand technical choices, I don't have enough knowledge of the qt ecosystem to be directive, so it has to provide me options. Of course in my own codebases, I give precise instructions like "plan implementing X by leveraging Y and look at how Z is done, do not go in the style of W which is pending a refactor". So both styles work if you let it help you.

https://drive.google.com/file/d/1ryx_wYc5ZGezUinaq15428nDiK46p2fH/view?usp=sharing

Yesterday I was with a friend who started building a small statistics app that reads numbers from photos of results of a video game, in half a day, he went from zero to having an android app that runs a custom image analysis model on-device and re-trains it on the fly with the corrections he gives to the readings... so my demo is quite bland.

Agents that can pilot a computer in addition of reading/writing the code are really a lever for your existing expertise. But giving them context that hints of existing expertise or strictness re: code will steer it more to a correctness space, while "build feature X" will make it act in a low-effort way.

Lastly, as Julien said, this will be obsolete in a few months.

And, I don't plan on proposing the results of this session, I need to research C++/QT e2e testing more. But it proved me that there are paths to do it. I'll scrap it and rework it.

@gr5

gr5 commented Nov 8, 2026

Copy link
Copy Markdown
Collaborator

Thanks for posting @Lucassifoni - I watched Julien's video and it was helpful to me as a complete novice. I will watch yours also and I'm okay with fast forwarding through lots of video.

@Lucassifoni - could you also look at the agents.md file in this PR and let us know what you think? Please be honest as I don't know what are good and bad practices with agents.md files. It seems to me that maybe an agent should be writing that and not a human.

@Lucassifoni

Copy link
Copy Markdown
Contributor

@gr5 I also think those files should be generated and periodically reviewed by agents. My own guidance files are periodically rewritten by Claude as each iteration of the model judges the previous instructions to be too "hand-holding" and detailed. My first iteration was manually written of course, and I've found behaviour degrading over time due to instructions I had insisted on keeping to match my human way of thinking about the codebase. But as the field constantly moves it is hard to back those claims with facts.

My rule of thumb is that if it's meant to be read passively by robots, it might as well be written by robots.

But I'll read it and get back to you.

@atsju

atsju commented Nov 9, 2026

Copy link
Copy Markdown
Collaborator Author

btw, this one has also been written by agent. It's a baseline that can be modified.

@gr5

gr5 commented Nov 12, 2026

Copy link
Copy Markdown
Collaborator

btw, this one has also been written by agent. It's a baseline that can be modified.

Oh! Then I approve this PR.

@gr5

gr5 commented Nov 15, 2026

Copy link
Copy Markdown
Collaborator

I've filmed one, but I'm sorry, it is 55 minutes long ... here it is.

Watched. Thanks for this. One thing I learned (of many):

@atsju - did you know you can install an extension to the gh utility called "act" that lets you test yaml files and github actions on your desktop the way github does it? (google netkos/gh-act)

@Lucassifoni

Copy link
Copy Markdown
Contributor

Hi @gr5, what I wanted to highlight the most is what some call "latent space steering" aka push the model in a direction that makes it more efficient. I've really witnessed this by helping non-developer friends start to use Claude, the vocabulary employed (and the presence or absence or technical jargon, emphasis on the need to learn/review/understand or not) really changes the output. Some call that "latent space engineering" but it's more like hitting a blackbox with a stick "the right way" to get better output. That said, those models do produce useful work.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

AI usage question

3 participants