# Setup

> Add Devbook to a project by hand, see how Claude and Copilot load the instructions and their limits, and learn how to update or remove it.

The [setup prompt](/#setup) 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.

<Tabs syncKey="method">
<TabItem label="Submodule (tracks updates)">

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

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

</TabItem>
<TabItem label="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.

```sh
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`](https://github.com/nitinraturi/devbook.raturi.in/archive/refs/heads/main.zip). Copy its `instructions/`, `stacks/` and `templates/` folders into `.devbook/`.

</TabItem>
</Tabs>

## 2. Connect your assistants

<Steps>

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.

   ```md title="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:

   ```md
   @AGENTS.md
   ```

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

   ```md title=".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.

</Steps>

## 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.

<Aside type="caution" title="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.
</Aside>

## 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

<Tabs syncKey="method">
<TabItem label="Submodule (tracks updates)">

```sh
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
```

</TabItem>
<TabItem label="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.

</TabItem>
</Tabs>

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](/license/). You can copy and change the files in any project without keeping a notice.