How do I keep the architectural context up to date?

You can run the included sync script after committing new changes to incrementally update the models with the latest commit context.

What kind of information do the models provide?

Models include details on how components work, why they were built that way, system invariants that must remain true, and known issues or fragile areas.

How does Code-Aware build architectural memory?

It scans your project's git history to analyze commit messages and code diffs, extracting the rationale behind changes to build structured Markdown models of each component.

Where are the architectural models stored?

All models, insights, and indices are stored locally in your repository's .code-aware/ directory in human-readable Markdown format.

Does it work with large repositories?

Yes. It offers a quick scan of the last 50 commits (usually under 2 minutes) for immediate use and a full scan option for deeper architectural coverage that can run in the background.

Architectural Memory (Code-Aware)

Name: Architectural Memory (Code-Aware)
Author: finereli

byfinereli

•

Learning & Documentation

Enhances AI agents with deep architectural context by extracting design rationale and component models from git history.

Code-Aware transforms raw git history into a structured architectural memory for AI coding agents. By analyzing previous commits, it reconstructs the reasoning behind specific code decisions, identifies component boundaries, and documents system invariants and known pitfalls. This allows Claude to operate with the context of a long-term maintainer, ensuring that new code changes align with original design philosophies and avoid repeating past mistakes. It is particularly useful during onboarding, complex refactoring, or when investigating regression issues in unfamiliar parts of a codebase.

Key Features

01Git-based architectural extraction and analysis

02Incremental synchronization to keep models current with new commits

031 GitHub stars

04Automated narrative developer notes generation

05Discovery of natural component boundaries and models

06System-wide architectural insights and opinionated observations

Use Cases

01Onboarding to complex or legacy codebases with missing documentation

02Debugging unexpected breakages by identifying fragile areas and past failures

03Planning major architectural refactors while maintaining system invariants

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add finereli/code-aware code-aware

For use in Claude.ai and ChatGPT

Download Skill