adlc-team-skills Teaches Agents Team Rules

adlc-team-skills is Tikalk's open-source GitHub project for packaging team coding rules as agent skills for Claude Code, Anthropic's coding agent, and Codex, OpenAI's coding agent. It deals with a boring but expensive problem: coding agents start fresh, while teams carry years of conventions, ADRs, deprecated patterns, and review habits. The useful idea is not more prompt stuffing; it is a small, versioned index that lets an agent pull the right rule only when the task needs it. That makes it a sharp example of how to implement code review habits for ai-generated code without turning every prompt into a policy document.

Read the release as a small index, not a giant handbook

adlc-team-skills is built around a simple move: start the agent with an index of team directives, not the full directives themselves. The README says team-boot injects names and one-line descriptors for rules, personas, and decisions at session start, roughly a hundred tokens. When a task touches SQL, the agent can load the SQL rule. When it does not, the SQL rule stays out of context.

An agent skill is a reusable instruction package that teaches a coding agent when and how to perform a specific workflow. In this repo, the skill names matter because they become the activation surface. A vague descriptor makes the agent guess. A crisp descriptor gives it a chance to load the right thing at the right time.

The second major piece is mission-brief. It pushes the agent to write down a contract before implementing: goal, constraints, non-goals, and success criteria. That is the part that feels most useful in real work, because many bad agent diffs start before code is touched. The agent silently fills a gap, then the reviewer has to reverse-engineer the assumption.

As of August 2026, the repository is small and early: 109 GitHub stars, MIT licensed, mostly Shell, and last pushed on August 5. The README is also dense. That matters. The Hacker News reaction split between people who liked the direction and people who thought the framing was overwrought or too hard to read. Both reactions are fair.

Notice what is clever and what is still rough

The clever part is the indirection. Teams already keep decisions in ADRs, review comments, Slack threads, wiki pages, and half-remembered conventions. adlc-team-skills asks you to put the durable parts in a git repo called team-ai-directives, then review changes by pull request.

That is better than a private machine-level memory file. Personal agent notes drift. They also fail the moment another teammate, editor, or coding agent starts the same task.

For Cursor, Anysphere's AI code editor, the same shape maps well to scoped rules and reviewable IDE workflows. A root rule can describe repository-wide expectations. A narrower rule beside packages/billing can say that billing code never calls the legacy invoice service directly. Local rules beat one giant instruction blob because the agent has fewer chances to obey the wrong rule.

The rough part is enforcement. A skill can remind an agent, but it cannot prove the architecture is safe. Static analysis, tests, type checks, and architectural constraints still do the boring work. If a rule says controllers must not import database clients, an ArchUnit-style test or import linter is stronger than a paragraph of guidance.

This is the useful lens for the related training topic: skills are not governance by themselves. They are a way to make the right rule visible early enough that the diff has a better chance.

Compare skills with memory files and checks

The project lands in a crowded space: memory files, Cursor rules, AGENTS.md, lint rules, tests, and MCP-connected knowledge bases. The mistake is treating those as competitors. They solve different failure modes.

Verdict: adlc-team-skills wins when the missing piece is shared context at task start. A big memory file wins for tiny repos or solo work where drift is low. Deterministic checks win whenever the rule can be expressed as code, because a failing check is clearer than a disappointed reviewer.

Try it on one small Cursor repo

Do not start with your whole engineering handbook. Pick one boring repo, one recurring review complaint, and one agent path. A good first test is a small service where SQL changes often miss migration notes.

Clone the project, read the scripts, then create one directive in your own repo that mirrors the idea without committing to a broad system yet.

git clone https://github.com/tikalk/adlc-team-skills /tmp/adlc-team-skills
mkdir -p .cursor/rules docs/ai-directives

Use a concrete rule, not a philosophy. For example: any change under packages/api/orders that edits SQL must include a migration, a rollback note, and an explanation for slow queries. Ask the agent to change an orders endpoint. Then review whether it asked for the missing contract, loaded the right rule, and produced a diff that a human can review without replaying the whole chat.

This is also a clean way to implement code review habits for ai-generated code in practice. You are not asking reviewers to trust the agent. You are asking the agent to leave a better review trail: what rule applied, what assumption it made, and what still needs human judgment.

The trap is measuring the chat instead of the diff. A polite agent that says it followed the rule is not evidence. The changed files, tests, and PR note are the evidence.

Copy this Cursor review rule

Put this in .cursor/rules/ai-review.mdc for a small experiment. Keep it narrow. Delete anything your repo cannot actually review.

---
description: Review AI-generated changes before merge
globs:
  - **/*
alwaysApply: false
---

Use this rule when a coding agent produced or edited the diff.

Review checklist:
- [ ] The diff follows the nearest AGENTS.md or Cursor rule, not only the root convention.
- [ ] The agent states which repo rule or directive applied to the changed files.
- [ ] Any generated test fails for the right reason before it passes, or the PR explains why that was not practical.
- [ ] Database, auth, billing, and permission changes include a human-readable risk note.
- [ ] The PR description lists assumptions separately from facts verified by tests or commands.
- [ ] CI, type checks, and lint checks are run locally or in the PR before merge.
- [ ] Review comments target the diff and artifacts, not the agent transcript.

If you also keep AGENTS.md files, draw a boundary. Put durable repository rules in AGENTS.md, task-specific review habits in Cursor rules, and broader team directives in a reviewed docs folder or separate directives repo. The exact file layout matters less than making every instruction reviewable.

Common questions

• What are the best ways to implement code review habits for ai-generated code?

  Start with one review checklist, one scoped rule, and one deterministic check. The checklist catches human judgment issues, the scoped rule gives the agent local context, and the check catches repeatable mistakes. For a first pass, use 6 to 8 review items and apply them to one repo before expanding.

• Is adlc-team-skills just a bigger CLAUDE.md?

  No. The interesting part is that it avoids loading the whole rulebook at once. team-boot starts with a compact index, while full directives are pulled only when the task matches. That is different from a large always-on memory file, though both can drift if nobody reviews the contents.

• Will this increase token burn and review surface?

  Yes, a little, and that is the honest tradeoff. The README describes an index of roughly a hundred tokens, which is small, but the full system still adds files, review decisions, and time. It is worth testing only where repeated agent mistakes already cost more than the added ceremony.

• Does this replace static analysis, tests, or CI?

  No. Skills are best for intent, context, and task contracts; checks are best for enforceable rules. If a boundary can be expressed as an import rule, type check, migration test, or CI command, make it deterministic. Use the skill to tell the agent why the rule exists.

• Where does MCP fit in this pattern?

  MCP fits when the agent needs external context from GitHub, Jira, docs, databases, or internal systems. The Model Context Protocol gives tools a common integration shape, but it also increases the need for permissions and session review. A directive index should say when to fetch context, not grant broad access by default.

Best ways to use this research

• Best for: Evaluating whether agent skills can carry team conventions into Claude Code, Codex, and Cursor without stuffing every prompt with a handbook.
• Best first artifact: Create one Cursor .mdc review rule and one directive for a recurring mistake, such as SQL migrations or auth checks.
• Best comparison angle: Compare a tiny directive index against a giant memory file and against deterministic checks. Each catches a different class of failure.
• Best caveat: Treat adlc-team-skills as an early open-source experiment, not a finished operating model. The README has good ideas, but it asks readers to do some assembly.
• Best telemetry question: If directives later call tools through MCP, ask how you will review what context was fetched. We looked at a related angle in Armature Adds Analytics for MCP Sessions.

Further reading

• Cursor — Agent
• Model Context Protocol — specification
• adlc-team-skills — source
• Google Search Central — helpful, people-first content

Try the smallest useful version

Pick one annoying review failure and encode only that. If the next agent diff is easier to review, you have a useful pattern; if not, delete the rule and keep the deterministic checks.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.