https://github.com/halfhp/repo-docs-with-claudemd
An exploration of a symbiotic relationship between CLAUDE.md and README.md
https://github.com/halfhp/repo-docs-with-claudemd
Last synced: 6 months ago
JSON representation
An exploration of a symbiotic relationship between CLAUDE.md and README.md
- Host: GitHub
- URL: https://github.com/halfhp/repo-docs-with-claudemd
- Owner: halfhp
- Created: 2025-07-21T16:51:21.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-07-21T17:27:33.000Z (about 1 year ago)
- Last Synced: 2025-07-21T19:25:28.977Z (about 1 year ago)
- Size: 9.77 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Overview
This repo is an exploration of how a repo `README.md` and a `CLAUDE.md` can live together and share common information. The goals are:
* Minimizing the need to update multiple files when new shared content is created.
* Avoid the risk of information going out of sync by maintaining multiple versions of the same information.
* Keep context passed to the LLM as small and focused as possible. In other words avoid sucking `README.md` into `CLAUDE.md`
The approach demonstrated here is to maintain common sections in `CLAUDE.md` and then link to them from `README.md` ensuring that only information that is explicitly meant for Claude is included as context. An alternative approach would be to use a more formal docs directory with separate markdown file for each common topic. The main objections to this approach are that it can be overkill for simple projects and requires:
1. create the new snippet file
2. link to the snippet in `CLAUDE.md`
3. link to the snippet in `README.md`
as opposed to:
1. add the section to `CLAUDE.md`
2. link to the new section in `README.md`
One potential additional advantage is that it's been reported that Claude Code is inconsistent about pulling in and consistently following context from external files. Certainly issues also exist with consistently following what's provided in `CLAUDE.md` but the general sentiment seems to be that the fewer degrees of separation, the more likely it is to work as expected.
# Coding Conventions
See [Coding Conventions](./CLAUDE.md#coding-conventions)
# Design Patterns
See [Design Patterns](./CLAUDE.md#design-patterns)