A Second Brain for Software Teams: Docs, Skills and AI Agents

Two teams, two very different contexts, the same problem: the knowledge you need to do the work lives in people's heads and in chat threads. This is how I built a "second brain" for both, made of layered documentation, skills and AI agents: what worked, what didn't, and the numbers.

Every development team reaches the moment it realizes it depends on a handful of people. The server only one person knows how to restart properly. The go-live procedure that "is written down somewhere". The incident from six months ago that happens again, identical, because the lesson stayed in a chat. The outgoing vendor who leaves behind a handover call and a few PDFs.

AI coding agents made this problem more urgent, not less. An agent that doesn't know how your infrastructure is built makes the same wrong assumptions as a new hire, just faster and with more confidence. But they also made the fix finally worth it: well-written documentation no longer serves only people. The agent reads it too, every single time, without getting tired.

In practice it is a company knowledge base built for AI agents: documents, rules and procedures written so that both a colleague and an agent can use them. This article is a case study, not a theory. Both projects are real and anonymized.

Who it's for: CTOs, tech leads and senior developers at agencies and in-house teams who use, or want to use, AI agents (Claude Code or similar) on real work: maintenance, incidents, tickets, releases.

What it isn't: a Notion or Obsidian tutorial for personal notes. Here the "second brain" belongs to the team, and one of its main readers is an agent.

Contents

The two contexts

An e-commerce agency. About 17 Magento stores in production on a shared cluster, 29 store repositories, around fifty internal modules shipped as Composer packages. The typical work is operational: a store slows down, a bot floods the cache, a security patch must reach every store, a new client must go live without skipping a single step.

A university portal. A backend, a mobile app, a CRM, a booking system and a handful of inherited libraries, taken over from an outgoing vendor. The typical work is different: understanding a system you didn't write, answering hundreds of user tickets, fixing things while being unable to ship code for months because of the academic calendar.

Opposite contexts, yet the structure that worked is the same: three layers, each resting on the one below.

Layer 1: layered documentation

The first mistake everyone makes is writing one huge instruction file for the agent. It works for a week, then it turns into a wall of rules nobody rereads and the agent applies poorly, because everything carries the same weight.

What worked is a hierarchy, from general to specific:

LevelWhat it holdsExample
Global (person)Rules that apply to every project"Code is changed locally only, never on the server"; "fetch before judging a branch"
WorkspaceOnly what applies to every session on that clientThe four anti-bot defenses that must not be confused with each other
DomainOne area with its own conventionsSecurity and monitoring: where logs live, how reports are named
Project or moduleCommands, architecture, build traps"The frontend bundle is committed, CI checks it's in sync"

The agency's workspace file states its purpose on the first line: it holds only the rules that apply to every session. Everything else is an index pointing to files the agent opens when needed. It's the same principle as good documentation for humans: you don't read everything, you know where to look.

Four more details turned out to be decisive:

  • Code documentation lives next to the code. In the university project the backend chapters were moved into the backend repository. A twenty-line placeholder ("Moved: see here") stayed behind so links wouldn't break, and chapter numbering stayed unique across both repositories.
  • A "where we left off" file. What was decided, what's open, where to restart. Whoever picks the work back up after a week reads it, person or agent.
  • The docs admit they can be wrong. Sounds like a detail, it's the opposite: the rule "the machine is the source of truth, the docs may be stale, verify" stops an agent from confidently applying a three-month-old procedure.
  • Gaps are declared. The go-live checklist has steps explicitly marked "not documented". A declared gap is information; a hidden gap is a trap.

Layer 2: skills, "how it's built" and "what to do"

A skill, in the sense of modern coding agents, is a package of instructions the agent loads when the task calls for it: a description that says when to use it, and a body that says how. The difference from any other document is that it gets triggered by context instead of being searched for.

The agency has two skills, and the split between them is the most useful part of the whole project:

  • "How it's built": the infrastructure. Which store runs on which server, which database, which cache. Ten rules that always apply. And above all a table of symptom, first hypothesis, file to open.
  • "What to do": taking a new store live. A 14-step checklist and 12 ordering constraints that cannot be swapped.

The symptom table is what saves the most time. It looks like this (simplified):

| Symptom                     | First hypothesis                 | Where to look          |
|-----------------------------|----------------------------------|------------------------|
| 503 on a single store       | PHP pool saturated by bots       | infra/varnish.md       |
| store slow after a deploy   | cache not warmed up              | infra/cache.md         |
| writes failing              | disk full (df -h before anything)| infra/storage.md       |

Instead of reasoning from scratch, the agent starts from the hypothesis an experienced colleague would try first, and opens one file instead of ten.

The ordering constraints share one property: each one carries the incident that created it, with date and context. "Configure the cache before the application environment", followed by what happened the one time it was done the other way round. That detail has a single purpose: preventing anyone, person or agent, from "simplifying" the rule because it looks unnecessary.

In the university project the same principle took a different shape: one skill per environment (dev, staging, production), each with read-only access recipes, the commands to run as the application user, and its own symptom and where-to-look table.

Layer 3: agents read, people write

The third layer is where agents stop being a chat assistant and become a work pipeline. The most complete case is ticket handling for the university portal: hundreds of user reports, many duplicated, many missing the information needed.

The pipeline is split into tasks with separate responsibilities:

  1. Fetch and import. Tickets are pulled from the client's system and imported into a local database, repeatably, with a change log and a dashboard.
  2. Classifier. Assigns each ticket a function, a symptom and a skill area, picking from a closed taxonomy (8 functions, 22 symptoms, 9 skill areas) built by reading the real tickets. It works in batches of 25, at most 4 instances in parallel, and uses a cheaper model because the task is high-volume. It doesn't look for root causes and strips personal data. A new taxonomy value must be approved by a person.
  3. Researcher. Investigates the why, read-only, in a fixed order: documentation, code on the remote branch, logs, production database. On the database it follows strict rules: one query at a time, a 20-second timeout, always a row limit, some tables off-limits. It produces a report with eight fixed sections.
  4. Resolver. Prepares the fix: the code change and, when needed, a SQL patch split into five files (check, write without commit, guard and commit, verify, rollback). It runs none of them. It also drafts the reply to the user.

The rule holding it all together is simple: agents read and propose, people write. No agent modifies production data. It's the same separation you'd apply to a new colleague's permissions, applied systematically.

Numbers from the first run:

  • 228 tickets covered by 6 research runs in about two and a half hours
  • 98 screenshots attached to tickets transcribed by 4 agents in parallel
  • 292 tickets classified in 12 batches, with 18 duplicates found and 9 flagged "needs review"

And a number you rarely see in AI articles: the classifier is measured. When the resolver reaches the actual root cause, it records whether the skill area assigned at the start was right. Result: confirmed in 79 cases out of 205, 39%.

39% isn't a failure, it's the reason the system is designed this way. The initial classification is there to sort and group, not to decide. Had it been used to assign work directly, six tickets out of ten would have landed on the wrong desk. Separating classification from analysis, and measuring the first with the second, is the only way to find out.

The loop that makes it grow: every incident becomes a rule

A second brain that doesn't learn is an archive. What made the agency's system useful over time is a very simple loop:

incident
   โ†“
post-mortem (fixed template: what happened, actions, lessons, what's still open)
   โ†“
the lesson becomes a rule in the skill, or a memory
   โ†“
the next similar incident starts from the right hypothesis

In a few months the agency built up 47 post-mortems and 77 memories. Memories come in three types: feedback (rules learned from corrections, like "never run the application CLI as root"), project (diagnosed cases, with symptom, cause and fix) and reference (where to find what).

The same method surfaced things that have nothing to do with AI but would never have emerged without documentation like this: while reconstructing the state of the stores' deploy pipelines, we found 34 diverging versions of the same workflow, across seven generations. Today there is one.

In the university project the loop starts even before incidents: at the handover. The call with the outgoing vendor was transcribed, structured, and then checked against the code, with a dedicated document listing the discrepancies between what was said and what the code actually does, each with a file and line reference. It's the single most useful document in the project.

From client request to production: what's covered

The original goal was to cover the whole path: from the first client contact to the feature, to testing, to production. Here's where things stand, no embellishment:

PhaseE-commerce agencyUniversity portal
Client request and requirements๐Ÿ”ด missing๐ŸŸก partial: tickets, email drafts listing the decisions needed, slide decks
Analysis and diagnosis๐ŸŸข strong๐ŸŸข strong
Reproducing the issue๐ŸŸก manual๐ŸŸข local environment impersonating the user on a slim dump
Development๐ŸŸข development and review skill, branches and PRs๐ŸŸข one worktree per fix, PRs
Testing๐Ÿ”ด almost none๐ŸŸก acceptance test cases written for the client, no automated tests
Go-live๐ŸŸข checklist with constraints๐ŸŸข runbook with rollback and migration log
Lessons learned๐ŸŸข very strong๐ŸŸข strong

The middle of the flow is solid. Both ends aren't: requirements gathering and testing are where the second brain doesn't help yet. That's no accident. They're the phases most tied to people (the client on one side, the judgment of "it works" on the other), and they're what I'm working on now.

What didn't work

A case study without this section is a brochure. Here are the real problems.

Written rules aren't enough. The researcher had an explicit rule: "read-only, no files on the server". Twice, an agent still wrote a temporary file on the production machine for convenience. No damage, but the lesson is clear: a guardrail that lives only in the prompt text is a suggestion. The important ones must be enforced with permissions and hooks that block the command before it runs.

Automated doc review is noisy. The skill that looks for duplicated or conflicting sections produced 99 candidates on its first manual run: about 6 were real actions, about 90 were noise. The fix was a "judge" agent per pair of files, required to cite file and line, explicitly told that "no problem" is a valid outcome. Plus one hard rule: duplicates get fixed, conflicts never do, because the information needed to pick the right version isn't in the docs, it's on the server.

Skills must travel with the code. In one project the skills folder was excluded from the repository. Result: anyone opening a session from another folder, or a colleague on another machine, didn't have them. If skills are team knowledge, they're versioned like everything else.

Secrets tend to end up in documents. Once the docs become the place where everything gets written, credentials and tokens end up there too "for convenience". Keep them out of documents from day one, and reference them with a placeholder.

I didn't measure time saved. I have ticket and incident numbers, not a rigorous before-and-after comparison. That's the next number I want.

How to start in your team

If I had to start from scratch tomorrow, I'd do this, in this order:

  1. A short instruction file per workspace, with only the always-on rules and an index of where everything else lives.
  2. A symptom, first hypothesis, where-to-look table for the system that hurts the most. Highest return of anything here.
  3. A fixed post-mortem template, and the habit of turning every lesson into a rule, together with the case that produced it.
  4. Split "how it's built" from "what to do" as soon as the docs grow past a few pages.
  5. Read-only agents for diagnosis and analysis, with writes always prepared and never executed.
  6. Enforced guardrails, not just written ones, for anything touching production.
  7. Measure at least one thing the agents do. That 39% taught me more than any demo.

A second brain isn't a tool you install. It's a team habit, writing down what you learn in the place where it will be needed, that AI agents have finally made worth the effort.

Related articles

Want a second brain for your development team?

I help agencies and technical teams build documentation, skills and AI agents around their real work: incidents, tickets, releases. Starting from what already exists, without rewriting everything.

Let's talk