Setup

The setup prompt does all of this for you. The steps below show the same setup done by hand.

1. Choose how to add Devbook

Both methods put the files in .devbook/, so the rest of the setup is the same. Pick a tab.

Submodule (tracks updates)

Follows main. You update with one git command, and every update shows up as a reviewable change.

git submodule add -b main https://github.com/nitinraturi/devbook.raturi.in .devbook

Copy (plain files)

Downloads plain files that you commit. It works offline afterwards, needs no submodule support from tools or cloud agents, and only changes when you download again.

rm -rf .devbook && mkdir -p .devbook && curl -fsSL https://codeload.github.com/nitinraturi/devbook.raturi.in/tar.gz/main | tar -xz --strip-components=1 -C .devbook devbook.raturi.in-main/instructions devbook.raturi.in-main/stacks devbook.raturi.in-main/templates

Without a terminal, download the ZIP of main. Copy its instructions/, stacks/ and templates/ folders into .devbook/.

2. Connect your assistants

1. Create AGENTS.md at the repository root. Fill in the Project section. In the Devbook section, keep only the lines that apply. Core, security and testing are mandatory. Add performance for any app or site, api-data for a backend or database, design for any UI, seo and content for public sites, and mobile for apps. Then add one stack note for each technology you use.

   AGENTS.md

   # AGENTS.md
   
   ## Project
   <!-- Project-specific facts and rules. Keep this section short; add to it as the project grows. -->
   - What: <one sentence: what this project is and who it is for>
   - Stack: <language, framework, hosting, database, package manager>
   - Commands: install `<cmd>` · dev `<cmd>` · lint `<cmd>` · typecheck `<cmd>` · test `<cmd>` · build `<cmd>`
   - Layout: <where pages, components, content, tests and scripts live>
   - Project docs: <links to design system, specs or domain rules, if any>
   - Rules: <project-specific rules; they override Devbook where they say so>
   
   ## Devbook
   Read and follow every file below before your first change in a session. Paths are relative to the repository root.
   
   @.devbook/instructions/core.md
   @.devbook/instructions/security.md
   @.devbook/instructions/testing.md
   <!-- Keep only the lines that apply, and delete the rest: -->
   @.devbook/instructions/performance.md
   @.devbook/instructions/api-data.md
   @.devbook/instructions/design.md
   @.devbook/instructions/seo.md
   @.devbook/instructions/content.md
   @.devbook/instructions/mobile.md
   @.devbook/stacks/<stack>.md

2. Create CLAUDE.md containing one line:

   @AGENTS.md

3. Create .github/copilot-instructions.md:

   .github/copilot-instructions.md

   Follow `AGENTS.md` at the repository root. Before your first change in a session, read every Devbook file it lists under `.devbook/`, then follow those rules for all work.

4. Commit .devbook (plus .gitmodules for a submodule), AGENTS.md, CLAUDE.md and .github/copilot-instructions.md, then start a new chat.

How the instructions load

• Claude Code reads CLAUDE.md, follows @AGENTS.md, then follows each @.devbook/... line. The full text is in context at the start of every session. Write the @ paths as plain text: an @ path inside backticks is not imported.
• GitHub Copilot (VS Code, the coding agent and the CLI) reads AGENTS.md and .github/copilot-instructions.md automatically. It does not inline @ lines. The sentence in copilot-instructions.md tells it to read those files, and it normally does. Still, this is an instruction, not a guarantee.
• Other agents that support AGENTS.md (such as Codex, Cursor and Gemini CLI) get the same file list.

Cloud agents and submodules

Hosted agents only see a submodule’s files if their checkout includes submodules. If an agent says the files are missing, add git submodule update --init to its setup steps. For the Copilot coding agent, those steps live in .github/workflows/copilot-setup-steps.yml. You can also switch to the Copy method, whose files are in the repository itself.

Cost

Each instruction file is 1.5 to 7.5 KB. The mandatory set (core, security and testing) is about 14 KB, around 3,500 tokens. A typical public website adds performance, design, SEO and content, for about 33 KB in total (around 8,500 tokens). An API service adds performance and api-data, for about 19 KB. That is a small share of a modern context window, and it loads once per session.

Update, clone or remove

Submodule (tracks updates)

git submodule update --remote .devbook       # pull the latest Devbook, then commit the change
git clone --recurse-submodules <your-repo>   # clone a project that uses Devbook
git submodule update --init                  # fetch .devbook in an existing clone
git rm .devbook                              # remove; then delete the @ lines from AGENTS.md

Copy (plain files)

Run the download command again, then review git diff .devbook and commit. The command replaces the whole folder, so files removed upstream are removed in your copy too. To remove Devbook, delete .devbook/ and the @ lines from AGENTS.md.

To switch from Copy to Submodule, delete .devbook/, commit the deletion, then run the submodule command.

Devbook has no version pins. Either way, your repository records exactly which Devbook text it uses, so an update is a normal reviewable change.

License

Devbook is MIT-0. You can copy and change the files in any project without keeping a notice.