Grok Code By Design

We build a tool that enables us to do the following:- Enable people to make important decisions quickly, while empowering agents to use complex ideas with less tokens.

Comment

Inspiration

  • Enable people to make the important decisions by enabling them to understand complex projects quickly
  • Maintain a living design document that evolves with the code
  • Empower agents to represent, and use complex ideas with less tokens, enabling them to better understand the codebase

What it does

  • Generate design docs with Grok agent that include:
    • Overview of the project, and its key dependencies
    • Definitive list of functionality (workflows) that the project provides
    • Design doc and mermaid diagrams documenting important data flow
    • List of relevant files for each workflow (this empowers grok to know where to look)
  • Utilize this rich condensed data to give Grok the appropriate context when reviewing pull requests

How we built it

We built scripts that run in a Github app with every build. These scripts use Grok CLI agent to understand the codebase, and generate the docs. A script also runs when someone submits a PR on GitHub, creating a visual representation of the main design changes. Our CI scripts are in a private repo since they contain the grok CLI binary

Challenges we ran into

Time

Accomplishments that we're proud of

The agent generated great design docs, and PR reviews, due to its condensed context. Look at projects under 'https://github.com/headless-test-customer, to see what we have generated for a wide vareity of open source projects. Some of the generated docs, and PR comments are below. : Grok-1 https://github.com/gauravagerwala/grok-1/tree/main/.exp - DESIGN docs

https://github.com/gauravagerwala/grok-1/pull/26/files

https://github.com/gauravagerwala/grok-1/pull/28/files - Generated visual descriptions of changes made in the PR

https://github.com/gauravagerwala/grok-1/pull/29/files - catches bad PR

https://github.com/gauravagerwala/grok-1/pull/31/files - simple PRs without design change

Rust-clippy

https://github.com/gauravagerwala/rust-clippy/tree/master/.exp - DESIGN docs

https://github.com/gauravagerwala/rust-clippy/pull/22/files - simple change, not showing any changes to the design of the system

https://github.com/gauravagerwala/rust-clippy/pull/8/files - interesting design change, showing added, removed, and updated components

X-ai-sdk

https://github.com/gauravagerwala/xai-sdk-python/tree/main/.exp - DESIGN docs

https://github.com/xai-org/xai-sdk-python/issues/77 - Found an issue in the x-ai-python-sdk which prevents users from using the client effectively for batch collection uploads. Our agent was able to identify this because of the appropriate context, created by it during the initialization phase.

What we learned

Grok CLI is pretty cool

What's next for Grok Code By Design

Run this for all open source repositories, and create a database of design docs that enable people to get the appropriate information visually (instead of spending hours with the code)

Built With

Share this project:

Updates