mattpocock

Problem with Spec driven development Hi everyone, I’m looking for some guidance on my workflow. I feel like I’m missing something. I started working on a project about two months ago and have been following Matt Pocock’s skills. It worked well at first. The grilling sessions were really helpful, and I got useful stories and documentation out of them. I also used AI to write some additional Markdown files for features that needed them. But now that I’m changing and reimplementing features, the docs just keep getting bigger. For example, I originally wanted guest login, then switched to Google sign-in, and now I’ve moved to third-party sign-in. Each change seems to add more to these already large files. I’m getting stuck on how to handle smaller changes: - If I just want to change a color, do I need to run /grill and go through the whole process? When I make quick design changes directly, those changes don’t get reflected in the docs. - What about small features? Following the full workflow every time is becoming a pain in the ass, and loading all this documentation is eating through my tokens. How are you handling this in your projects? When do you use the full workflow, and how do you keep the docs up to date when you make smaller changes?

AI Can Write More of the Code. We Still Have to Engineer the System. Originally published on picon.dev. Leer en español. When people say AI has transformed software development, I want to know which part they mean. Producing an implementation? Exploring a design? Deciding whether a system solves the right problem? Those activities are connected, but automating one does not settle the others. My argument is that agents can take on more implementation work, and assist with analysis, design, and testing, while engineers remain responsible for deciding what to build and what evidence is sufficient to accept it. That changes the work. It does not make the responsibilities disappear. I am wary of describing this as replacing the person who churns out code. It reduces developers to typing, understates what agents can assist with, and turns task automation into a claim about jobs. Claims about workforce replacement require evidence beyond an impressive demonstration. The practical question interests me more: how do we use these tools while keeping our decisions visible and our feedback useful? Give decisions somewhere to live A conversation is convenient for exploring options. It is a fragile place to keep the only record of an architectural decision. Model context is bounded. A long session may be summarized, compacted, or resumed with selected information. The summary can preserve the conclusion and lose the condition that made it reasonable. “Use a local cache” is different from “use a local cache because this screen must remain usable without connectivity.” Anthropic's account of long-running agents describes continuity problems across context windows and an approach using incremental work and persistent progress artifacts. It also reports that compaction can leave unclear instructions. This is a vendor engineering report about a particular setup, rather than a universal comparison of development workflows. My preference is to give durable decisions a small, reviewable home. A PROJECT_GUIDE.md might contain: - The product's purpose and current scope, including explicit exclusions. - The important system boundaries and the reasons behind architectural choices. - Quality expectations and the commands used to check them. - Links to deeper decisions when those decisions need more space. The filename has no special power. An agent will not necessarily load it automatically. I would connect it through the tool's supported project instructions or explicitly include it in the task, then check the agent's interpretation. For each increment, I would supply the relevant files and ask for a brief account of the intended change, constraints, and acceptance cases. A paraphrase is an early opportunity to catch misunderstanding; the implementation still has to demonstrate compliance. Simon Willison's June 2025 discussion of context engineering helps frame the problem of choosing information for the next model step. My narrower recommendation is to make that selection deliberate and inspect its consequences. Markdown alone guarantees neither retrieval nor obedience. Sending every document on every task can increase context and cost. Selective retrieval may reduce input, but maintaining documents, retrieving them, and correcting mistakes also consume resources. Any claim of savings needs a measurement of the complete task. Specify the next behavior Consider a hypothetical mobile search screen. This is an illustration, not a report from a completed project. The story could be: “As a user, I want to search saved items so that I can find an item without scrolling through the entire collection.” For the first increment, the scope is local search over existing items. Remote search and changes to persistence are excluded. Before implementation, I would make these acceptance cases explicit: - A matching query displays the expected items. - A query with no matches displays an empty result state. - Clearing the query restores the complete collection. - If filtering is asynchronous, an older result cannot overwrite a newer query's results. These cases expose a technical question: does filtering need asynchronous work at all? The agent can help assess that decision. We should resolve it against the expected data size and responsiveness requirements, rather than introducing concurrency because a template expects it. For this example, I might choose unidirectional data flow, explicit UI states, and a separation between filtering logic and rendering. That makes state transitions easier to inspect. Another system may justify a different structure; this is an engineering choice with a purpose. The project guide should preserve that purpose. Feature-level notes should explain the behavior and any new decision. They do not need to reproduce the entire architecture. After the increment, I would inspect the diff, run the relevant checks, and exercise the screen. If the agent rewrote persistence despite the scope restriction, passing tests would not make that expansion acceptable. If the empty state looks correct but the search matches the wrong field, a screenshot would not establish correctness either. Make generation answer to verification Agent output is probabilistic. Acceptance should depend on evidence that we can inspect and, where practical, reproduce. A local verification command can run formatting checks, static analysis, compilation, and focused tests. These checks answer different questions. A formatter checks conventions; a compiler checks language and type rules; tests evaluate selected behavior under selected conditions. None establishes that we chose the right product behavior. Controlled verification also needs controlled inputs. Tool versions, fixtures, and execution conditions matter. Tests involving timing, devices, networks, or external services may be flaky. Calling a test suite deterministic does not make it so. Even a perfectly repeatable check can verify the wrong thing. A search test might assert that some result appears without checking which result it is. A generated test can faithfully encode the same misunderstanding as the generated implementation. I would review the assertion against the acceptance case and use deliberately chosen examples, including a failure case. Running the app adds another kind of evidence: whether the behavior makes sense through the actual interface. When performance matters, define the measurement before declaring success—device, dataset, scenario, and threshold. A quick impression of responsiveness is useful feedback, but it is not a latency result. Hooks can make local checks convenient and catch mistakes earlier. Their coverage depends on what triggers them and whether they can be bypassed. Where a team requires enforcement, server-side checks and repository protections need their own configuration. A local hook is not equivalent to an enforced remote policy. The engineer still decides whether the evidence supports acceptance, revision, or rejection. An agent can help gather that evidence; it cannot make an incomplete test suite complete by announcing success. Documentation has to earn its maintenance I become skeptical when a small change requires a long chain of generated documents before anyone can see working behavior. Each document becomes something to review, reconcile, and keep current. Producing text cheaply does not make understanding it cheap. That is a criticism of proportionality and feedback cadence. Spec-driven development has multiple meanings. Birgitta Böckeler's 2025 examination of Kiro, spec-kit, and Tessl distinguishes approaches that write specifications first, retain them during maintenance, or treat them as the primary source. Those differences matter when discussing costs and control. François Zaninotto's critique of document-heavy workflows raises concerns about review overhead and instruction following through reported examples. Those cases are useful prompts for investigation. They do not establish that specifications generally cause worse outcomes. An incremental specification can support rapid feedback. Agile does not mean avoiding documentation: its principles emphasize frequent working software, technical excellence, and adaptation. A short acceptance case can serve those aims; so can a detailed design when the risk warrants it. Stronger specifications can be valuable for safety constraints, regulated work, public interfaces, migration compatibility, and coordination across teams. In those settings, a concise guide is an entry point to the necessary detail. It cannot replace that detail. My test for a document is practical: what decision, implementation, or verification does it support, and who will maintain it? I would keep the explanation of a compatibility constraint even if it takes several pages. I would remove repeated prose that neither changes a decision nor helps someone evaluate the work. Matt Pocock's collection of engineering skills offers another example of packaging guidance into adaptable, composable pieces. I find that direction useful. Its stated design goals are not evidence that a collection of skills outperforms another workflow. Keep the acceptance decision explicit A small increment can still contain a bad assumption. Its advantage is that it gives us an earlier, more bounded opportunity to discover one. The loop I would advocate is straightforward: define the next behavior, supply the context it needs, check the interpretation, inspect the change, collect evidence, and decide whether to accept it. Update durable guidance when a decision changes. If review becomes unmanageable, reduce the increment or improve the checks before asking the agent to produce more. This approach has limits. It depends on the engineer's understanding, the quality of the evidence, and the cost of keeping guidance current. This article presents a working position, not a controlled study or a demonstrated productivity gain. Establishing such a gain would require comparable tasks and accounting for review, rework, defects, and maintenance—not just generation time. I am comfortable delegating more of the work when I can explain what was requested, what changed, and why the evidence supports accepting it. That is the engineering standard I want to carry into AI-assisted development. Which decisions in your workflow remain visible after the conversation ends—and what evidence tells you that the agent respected them? --- Authorship note: The initial draft was generated with AI assistance from Armando Picón's arguments and a source review. Armando reviewed the article and approved publication. The Spanish translation was produced with AI assistance. The mobile example is hypothetical. The cover illustration was also generated with AI.

Why are your merge requests still stuck in review? I keep hearing these phrases: "Code is cheap" and "Code does not matter anymore." In a way, I kind of agree with both, but what does it even mean? We write code significantly faster nowadays than we did just a year or two ago. But we aren't producing better products or delivering higher business value. We aren't even always delivering features sooner than we did previously. The biggest bottleneck is the review process. By that, I mean the whole flow of code review, testing and other validations that check everything is ready to be shipped to production. The data from the industry says the same thing. Faros AI looked at about 10,000 developers in 2025: their teams merged 98% more MRs, but review time went up 91% and the MRs got 154% bigger. At Uber, the time to first review grew from 3 hours in 2024 to 9 hours in 2026. LinearB's 2026 benchmarks show that AI-assisted MRs are about 2.6x larger, and agentic AI MRs wait about 5x longer before someone starts the review. Most of these numbers come from companies that sell review or metrics tools, so take them with a grain of salt, but you can still get the idea from them. !Bar chart. Agentic AI merge requests wait 17.6 hours for the first review versus 3.4 hours for unassisted ones. AI-assisted changes are 408 lines versus 157 for unassisted. 75th percentile, LinearB 2026 Benchmarks. Stuck merge requests or longer review times mean longer lead times, which means moving slower in a world where there are teams shipping multiple features while you are reading this article. The best teams have already overcome this issue by automating the whole pipeline, from code generation to deployment to production. But the automation itself is not enough. We need to truly trust the system because otherwise we add some manual steps to it, and that breaks the whole idea. I find that the way we reviewed code in the past is the reason merge requests are still stuck. The bottleneck isn't new Code reviews have been the bottleneck since they were introduced, and they are still the bottleneck today. In a 2016 Microsoft study, developers named getting feedback in time as their top code review challenge, and the median time to approval was 24 hours. At Meta in 2022, the median review took a few hours, but the slowest 25% took more than a day. LinearB's data shows that waiting for pickup and review are the most frequent sources of delivery delays. There are, of course, some exceptions. Google is one of them. A 2018 study of about 9 million reviewed changes found that the median review took under 4 hours, with first feedback in under an hour for small changes. Their changes were small (a median of about 24 lines), most had one reviewer, OWNERS files made it easy to find the right reviewer, and their own guidelines say one business day is the maximum time to respond to a review request. The study also names the trade-off: one reviewer means less rigor. Why it is still stuck Nowadays, manually reviewing AI-generated code is even harder, and it takes even longer. The code is different no matter how many guidelines and coding principles you have in your documentation. The scope is usually bigger too. I remember reviewing my first few fully AI-generated merge requests at the end of last year. I was intimidated because I looked at them and had the feeling that this was something I could not keep up with. There were usually so many changes per review that I lost focus somewhere in the middle of the review almost every time. I was used to pulling the branch myself, seeing the changes, testing them myself locally and then commenting on the changes or approving the MR. Today, we are moving way too fast to still work that way. We have to build a system that will allow us to focus on the most important parts of the code that also have the biggest business value. Everything else needs to be automatically validated and reviewed. The system needs to be robust, so we truly trust it to deliver quality work. Otherwise, we end up putting some manual jobs in between just because we are afraid that something will break in production. How I review now I realized that I got lazy with code reviewing, and more things slipped through that would not have before. I knew I had to change something, and the most logical thing was to add more automated steps to my workflow to support the review of the AI-generated code. It is no secret that I use Matt Pocock's skills for pretty much everything, and of course, he has a skill named code-review. It looks at security issues and coding principles, and validates the changes that were made against the specs. It is quick and so far pretty good at discovering issues. There still needs to be some triage, and you should not blindly fix those issues, as some of them can also be false positives. But you should think about adding a comment to mark those spots, as otherwise some agent might fix them sometime in the future. This skill, together with the whole testing process where we add integration and regression tests, allows us to be less careful ourselves and ship features faster. At this point, I should mention that it is not just code that is cheap. Tests are also cheap. And just as we have to check the code, we should also check the tests to make sure they are relevant. Mutation testing is really useful for this, and I think I will write about it sometime in the near future. What the best teams do There is a lot of talk about AI software or development factories out there. The term means a system that automates everything from the idea to the release to production. It generates specs, implements the specs, reviews and validates/tests the code, and deploys it to production. The code review usually triages MRs by importance, risk and blast radius. The smallest and easiest ones get merged without a human involved and are also released to production. The big ones, and the ones that are important for the business, need manual verification, but the AI tells the reviewer which parts of the code need to be manually checked, so the reviewer does not need to go through all the code but just through the most important parts. !Flow diagram. A merge request goes to AI triage. Small and easy changes are merged automatically with no human. Big, risky or crucial changes get a human review, with AI pointing out what to check. In the first months a human confirms the triage. Pipeline guardrails such as linters and tests run on everything. When you are building such a system, you need to start small and automate each step separately, validate the output and then move to the next one. This is important to gain confidence that the system is working and that you will not be slowing it down manually. Of course, the tools that are already in place, such as linters, tests and other validation metrics, are the base for this kind of automation. This model can now be seen at multiple startups around the world, as they are usually the pioneers of all innovations. Airbyte sorts changes into low, medium and high risk, with AI classifying them from the ticket. Low-risk changes deploy without a review, and high-risk ones get a human review. They report 60–70% fewer unhealthy connectors with 30% fewer people. Uber's uReview decides how deep a review goes based on risk and complexity, and they plan to auto-approve some changes. At Agoda, humans own the spec and check the evidence instead of reading every line. Bugs will still happen There is no such thing as 100% reliability. There are cases where you have too many possible scenarios to cover in the validation process. We recently had one such case, where we deployed a release that fixed the main flow but introduced a bug in one of the edge case situations. Because this is a product that can be configured with more than 40 options, we can't test all of the possible combinations. Even if those options were just on/off options, it would take millions of years of testing. It's just not economical. !Bar chart on a log scale. Testing every combination of on/off options with 10 tests per combination at 3 seconds per test takes 8.5 hours for 10 options, about 1 year for 20, about 1,000 years for 30 and about 1 million years for 40. Bugs will happen even if we build the best and the most robust systems, because of the complexity of the products that we are building. It is most important that the cases with the highest business value are properly tested and validated, because there should be no room for error. But if some minor issue comes up with a new release, we should just take care to act quickly and fix it in almost no time. Observability tools help us find and fix things even before users notice or report them. The system needs to keep improving When the guardrails on the system miss something, we need to analyze it and see if it could have been avoided. If it could, we need to improve the system to prevent it in the future. We have to think about the system as a living thing that needs constant work and not as a finished project. The thing I learned from reviewing AI-generated code is that we should not be intimidated by the code or the process. We should embrace it, let the tools that we have review it and focus on the most important parts. Be confident in your system and keep improving it, because only then can we keep up with the pace we are moving at. References 1. Faros AI, research on AI and developer productivity (2025): faros.ai 2. Uber, "Building uReview: Uber's multi-agent code review" (AI Engineer talk): ai.engineer 3. LinearB, "Engineering benchmarks 2026: data from 8.1M pull requests": linearb.io 4. LinearB, "AI in software development: what the 2026 data shows": linearb.io 5. MacLeod, Greiler, Storey, Bird, Czerwonka, "Code Reviewing in the Trenches" (Microsoft, IEEE Software 2017): PDF 6. Meta Engineering, "Improving code review time at Meta" (2022): engineering.fb.com 7. LinearB, engineering metrics and cycle time: linearb.io 8. Sadowski et al., "Modern Code Review: A Case Study at Google" (ICSE 2018): research.google 9. Google Engineering Practices, "Speed of Code Reviews": google.github.io 10. Matt Pocock, skills: mattpocock/skills 11. Rootly, "How engineering leaders rethink code review in the AI era" (Airbyte example): rootly.com 12. InfoQ, Agoda on the AI code bottleneck (2026): infoq.com

Coding Agent の「作り直し」と「検証ミス」を減らす：Matt Pocock Skills × pstack 最近、Coding Agent を使った開発で、Matt Pocock Skills と pstack を組み合わせて使うことが増えています。 最初は便利そうな Skill を個別に試していただけでしたが、ソースコードやドキュメント、ほかの開発者の使用例を読んでいるうちに、それぞれの設計思想にも興味を持つようになりました。 実際に使い続ける中で、両者の良いところを取り入れた、自分なりのワークフローが少しずつ固まってきました。 特に役立っているのは、Spec を書いたのに UI が想像と違ったり、Agent がこちらの意図していない判断をしたり、変更後のアプリを検証したつもりが古いプロセスを確認していたり、といった問題への対処です。 この記事では、二つの Skills から学んだことと、普段の開発でどのように使い分けているかを紹介します。 1. Matt Pocock Skills と pstack は何を解決しようとしているのか どちらも Coding Agent を使った開発の信頼性を高めるためのものですが、アプローチには違いがあります。 1.1 Matt Pocock：コードを書く前に立ち止まる Matt Pocock（@mattpocockuk） は、TypeScript の教育コンテンツ「Total TypeScript」や「AI Hero」などを手がける開発者です。彼が公開している Matt Pocock Skills の特徴は、一般的なエンジニアリングプラクティスを、小さく独立した Skill に分けている点です。 Coding Agent は短時間で機能を実装できますが、実際に使っていると、次のような問題によく遭遇します。 要件が十分に決まっていないのに、Agent が実装を始めてしまう 実装の途中で、考慮していなかったエッジケースに気づく Spec には沿っているのに、完成した UI が自分のイメージと違う 実装が終わってからテストを追加し、大幅な修正が必要になる どれもソフトウェア開発では昔からある問題ですが、コード生成が速くなったことで、むしろ遭遇しやすくなったと感じています。 Matt Pocock Skills には、こうした問題に対応するための Skill が用意されています。 Skill 主な用途 /grill-me 質問を繰り返し、未決定事項や曖昧な要件を洗い出す /grill-with-docs 要件を議論しながら、用語集やアーキテクチャ上の決定事項をドキュメントに残す /prototype 本実装に入る前に、複数の設計案を試す /to-spec、/to-tickets 議論した内容を Spec や実装タスクに整理する /tdd Red → Green → Refactor のサイクルで実装する /code-review コード品質や元の要件との整合性をレビューする /handoff 別の Agent セッションに作業を引き継ぐため、進捗や決定事項を記録する 個人的に気に入っているのは、Agent がすぐにコードを書かず、質問するための仕組みがあることです。 例えば /grill-me では、未決定の部分を Agent が勝手に補完するのではなく、質問としてこちらに返してくれます。 また、/prototype では、本実装に入る前に、使い捨てのコードでアイデアを試すことができます。 どちらも、設計を早い段階で決めつけてしまうことを防ぐのに役立っています。 1.2 pstack：Agent が実際に何を検証したのか確認する Lauren Tan（@poteto）が開発した pstack は、タスクごとのワークフローと検証をより重視しています。 機能開発、デバッグ、調査、設計、レビューなど、さまざまな開発タスクに対応した Skill が含まれています。 代表的なものをいくつか挙げます。 Skill 主な用途 /poteto-mode タスクに応じて適切なワークフローを選択する /create-verification-skill プロジェクト固有の起動・検証手順を作成する /maintain-verification-skill プロジェクトの変更に合わせて検証手順を更新する /debug 修正する前に、不具合の原因を調査する /how、/why システムの動作や設計上の判断を追跡する /architect 実装前にモジュール構成や型の設計を整理する /unslop AI が生成した UI にありがちなデザイン上の問題を見直す 特に興味を持ったのが、Verification 関連の Skills です。 Coding Agent を使っていると、作業の最後に次のような報告を受けることがよくあります。 Implementation complete. All tests passed. もちろん、テストが通ったこと自体は良いことです。ただ、最近は「実際に何をテストしたのか」を確認するようにしています。 例えば、Agent が API を修正し、ユニットテストはすべて通過したものの、アプリケーション自体は起動していないケースがあります。 あるいは、コードの変更前から動いているサーバーにリクエストを送っていることもあります。 後者は自分も実際に遭遇した問題です。 /create-verification-skill を使うと、プロジェクトに合わせた起動・検証手順を Agent に覚えさせることができます。 起動コマンドや環境設定、起動完了の確認、機能の操作方法、どのような証拠があれば成功と判断できるか、といった情報をまとめられます。 毎回 Agent に一から調べさせるより、一度決めた手順を再利用できるほうが便利だと感じています。 1.3 二つの Skills をどう組み合わせるか もちろん、両者の機能には重複があります。 Matt Pocock Skills にも TDD、コードレビュー、デバッグ関連の Skill がありますし、pstack にも計画、設計、調査のためのワークフローがあります。 そのため、「Matt はコードを書くため、pstack はテストするため」と単純に分けているわけではありません。 自分の場合は、開発の各段階で次のように使い分けています。 開発段階 避けたい問題 主に使う Skills 実装前 要件が曖昧、設計の方向性が違う Matt：要件の確認、Prototype 実装中 変更範囲が大きすぎる、Spec から外れる Matt：タスク分割、TDD、レビュー 実装後 テストは通るが、実際のアプリの動作が違う pstack：プロジェクト固有の実行時検証 継続開発 Agent がプロジェクトの動かし方を忘れる、検証手順が古くなる pstack：Verification の更新、Matt：Handoff これは公式に用意された組み合わせではなく、自分が普段の開発で使っている方法です。 2. 実際の開発での使い方 すべてのタスクで、すべての Skill を使うわけではありません。 ただ、新しい機能を作るときは、次のような流れで進めることが増えました。 Step 1：まず要件を整理する 使用する Skills：/grill-me、/grill-with-docs 複数の実装方法が考えられる機能では、まず Agent に質問してもらいます。 例えば、プロジェクトの進捗に応じて、毎日のタスクを自動調整する機能を作るとします。 「計画が変わったらタスクを自動更新する」という要件だけでは、まだ分からないことがあります。 Agent はタスクをすぐ変更してよいのか。ユーザーの承認が必要なのか。手動で編集したタスクはどう扱うのか。 こうした部分を /grill-me で整理します。 長期開発のプロジェクトでは /grill-with-docs も使い、決定事項をドキュメントに残すようにしています。 Step 2：Spec ができても、すぐに本実装しない 特に気に入っている Skill：/prototype Matt Pocock Skills の中で、個人的に最も効果を感じている Skill です。 以前は Agent と十分に議論して Spec を書いたあと、そのまま実装に進むことが多かったのですが、完成した画面を見て、「確かに指定したとおりだけど、思っていたものと少し違う」と感じることが少なくありませんでした。 特に UI やインタラクションでは、文章だけで完成形をイメージするのが難しいです。 そこで最近は、設計がまだ決まっていない場合、三つの Prototype を作ってもらうようにしています。 例えば、タスク管理画面なら次の三案です。 リスト形式：優先度やタスクの状態を一覧で確認する カンバン形式：タスクをステータスごとに管理する タイムライン形式：日々の予定やスケジュールを中心に表示する 実際に動かして比較すると、どの操作が使いやすいか、自分が何を重視しているかが分かってきます。 その結果を Spec に反映してから本実装に進むほうが、あとから大きく作り直すケースを減らせています。 Prototype は基本的に使い捨てです。データベースや本番用のアーキテクチャまで用意せず、アイデアを検証することに集中します。 Step 3：方向性が決まったら実装する 使用する Skills：/to-spec、/to-tickets、/tdd Prototype で方向性が決まったら、Spec を更新して実装タスクに分割します。 入力と出力が明確なビジネスロジックについては、/tdd を使って小さく実装していくことが多いです。 ただし、単純な UI 修正まで毎回 TDD にするわけではありません。変更の規模や性質に応じて使い分けています。 Step 4：実際のアプリで検証する 特に気に入っている Skill：/create-verification-skill 以前は、機能が完成したら Agent に「アプリを起動して確認して」と指示するだけでした。 しかし、どのディレクトリで実行するのか、どのポートを使うのか、起動完了をどう判断するのかといった情報が曖昧だと、Agent が毎回試行錯誤することになります。 そこで /create-verification-skill を使い、プロジェクト専用の検証手順を作っておきます。 基本的には、次の流れです。 フェーズ 内容 Launch アプリを正しく起動する Doctor 環境やプロセスの状態を確認する Drive 実際に API や UI を操作する Evidence レスポンスやログなど、検証結果を残す Cleanup 検証用に起動したリソースを片付ける Feature Map には、主要な機能の操作方法や確認項目も記録できます。 毎回 Agent に起動方法から考えさせるのではなく、同じ手順で検証してもらえるのが気に入っています。 Step 5：問題があれば調査し、手順を更新する 検証中に問題が見つかったら、Matt の /diagnosing-bugs や pstack の /debug などを使い、原因を調べます。 修正後は同じ手順で再検証します。 プロジェクトの構成や検証方法が変わった場合は、/maintain-verification-skill で手順を更新します。セッションをまたぐ作業なら /handoff も使います。 普段のワークフローを図にすると、おおよそ次のようになります。 機能の要望 | v /grill-me または /grill-with-docs | v 最初の Spec | +-- 設計がまだ不確か？ | | | +-- /prototype | | | +-- 複数案を比較 | +-- Spec を更新 | v /to-spec と /to-tickets | v /tdd または段階的な実装 | v プロジェクト固有の Verification Skill | +-- Launch / Doctor +-- Drive +-- Evidence +-- Cleanup | v 問題が見つかった？ | +-- 原因を調査 +-- 修正 +-- 再検証 | v 完了 または /handoff この流れは、必ず守るチェックリストというより、作業を進める際の目安です。 また、二つの Skills を組み合わせるといっても、インストールするだけで自動的に連携するわけではありません。利用する Coding Agent や実行環境に合わせて使い分けています。 3. デモ：5つのStepでタスク管理アプリを作る ここまで紹介したワークフローを、小さな Python アプリの開発に当てはめてみます。 作るのは「今日のタスク管理アプリ」です。タスク一覧を表示し、完了ボタンを押すと状態が更新される、というシンプルな機能です。 以下は各 Skill の組み合わせ方を説明するためのデモであり、実際の Agent セッションの実行ログではありません。 Step 1：/grill-me で要件を明確にする 最初に Agent に渡す要件は、これだけです。 今日のタスクを表示して、完了できる Web アプリを作りたい。 /grill-me で要件を整理すると、例えば次のような質問が出てきます。 Agent からの質問 今回の決定 タスクの追加・削除は必要？ 今回は不要 完了済みタスクはどう表示する？ 一覧に残し、「完了」と表示する 完了ボタンを押したら？ ページをリロードせずに表示を更新する データの永続化は必要？ 今回は不要。メモリ上で管理する 存在しないタスク ID は？ HTTP 404 を返す ここで決めた「ページをリロードせずに表示を更新する」という仕様が、あとで重要になります。 Step 2：/prototype で UI を比較する 次に、同じモックデータを使って三つの UI を試します。 Prototype UI 特徴 A リスト形式 タスク一覧と完了ボタン B カンバン形式 未完了・完了の2列 C タイムライン形式 時間帯ごとのタスク表示 今回は最もシンプルな A のリスト形式 を採用します。 本来であれば三つの Prototype を実際に動かして比較しますが、このデモでは UI の選定結果を前提として進めます。 Step 3：/to-spec と /tdd で実装する 今回の最小限の Spec は次のとおりです。 GET /tasks：タスク一覧を取得する POST /tasks/{id}/complete：指定したタスクを完了にする /：タスク一覧と完了ボタンを表示する 完了操作後、ページをリロードせずに表示を更新する API と UI を実装タスクに分け、まず API の動作を /tdd で確認します。 test_app.py from fastapi.testclient import TestClient from app import app, tasks client = TestClient(app) def test_complete_task(): tasks[1]["done"] = False response = client.post("/tasks/1/complete") assert response.status_code == 200 assert response.json()["done"] is True assert client.get("/tasks").json()[0]["done"] is True このテストに対応するアプリを実装します。 app.py from fastapi import FastAPI, HTTPException from fastapi.responses import HTMLResponse app = FastAPI() tasks = { 1: {"id": 1, "title": "仕様を確認する", "done": False}, 2: {"id": 2, "title": "画面を確認する", "done": False}, } @app.get("/tasks") def list_tasks(): return list(tasks.values()) @app.post("/tasks/{task_id}/complete") def complete_task(task_id: int): if task_id not in tasks: raise HTTPException(status_code=404) tasks[task_id]["done"] = True return tasks[task_id] @app.get("/", response_class=HTMLResponse) def index(): return """ <h1>今日のタスク</h1> <ul id="tasks"></ul> <script> async function refresh() { const items = await (await fetch("/tasks")).json(); document.getElementById("tasks").innerHTML = items.map(t => ` <li> ${t.title}: <span id="state-${t.id}"> ${t.done ? "完了" : "未完了"} </span> <button onclick="completeTask(${t.id})"> 完了にする </button> </li> `).join(""); } async function completeTask(id) { await fetch(/tasks/${id}/complete, { method: "POST" }); } refresh(); </script> """ 依存パッケージをインストールし、テストを実行します。 pip install fastapi uvicorn pytest httpx python -m pytest -q この API テストは通ります。 しかし、まだ一つ問題が残っています。 Step 4：Verification Skill で実際の動作を確認する Step 3 では API のテストが成功しました。しかし、ここで Agent が pytest の結果だけを見て実装完了と判断すると、問題を見逃してしまいます。 まず、Verification Skill を使わずにアプリを確認してみます。 python -m uvicorn app:app --port 8000 ブラウザで localhost を開き、「仕様を確認する」の完了ボタンを押します。 画面上の表示は、次のままです。 仕様を確認する：未完了 一方、API を確認すると、 curl localhost 次のように状態が更新されています。 [ {"id": 1, "title": "仕様を確認する", "done": true}, {"id": 2, "title": "画面を確認する", "done": false} ] API 自体は正常に動作しています。それでも、ブラウザ上では「未完了」のままです。 もし Agent が API のレスポンスだけを確認していたら、この不具合を見逃す可能性があります。 そこで、pstack の /create-verification-skill を使い、プロジェクト固有の検証手順を用意します。 今回なら、次のような内容です。 フェーズ 検証内容 Launch 現在のコードを新しいプロセスで起動する Doctor プロセスとポートを確認し、起動完了を待つ Drive ブラウザでタスクの完了ボタンを押す Evidence API と画面表示の両方を確認する Cleanup 今回の検証で起動したプロセスを終了する ここでは、その検証方法を簡単な Python スクリプトで再現します。 ブラウザ操作には Playwright を使います。 pip install playwright python -m playwright install chromium verify.py を作成します。 import json import socket import subprocess import sys import time from urllib.request import urlopen from playwright.sync_api import sync_playwright, expect 既存のサーバーを避けるため、空いているポートを選ぶ with socket.socket() as sock: sock.bind(("127.0.0.1", 0)) port = sock.getsockname()[1] url = f"http://127.0.0.1:{port}" 現在のコードを新しいプロセスで起動する server = subprocess.Popen( [ sys.executable, "-m", "uvicorn", "app:app", "--host", "127.0.0.1", "--port", str(port), ], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, ) try: 新しいサーバーの起動を待つ for _ in range(50): if server.poll() is not None: raise RuntimeError("Server failed to start") try: with urlopen(f"{url}/tasks", timeout=1): break except OSError: time.sleep(0.1) else: raise TimeoutError("Server not ready") with sync_playwright() as p: browser = p.chromium.launch() try: page = browser.new_page() page.goto(url) 初期状態を確認する state = page.locator("#state-1") expect(state).to_have_text("未完了") 実際に完了ボタンを押す with page.expect_response( lambda r: "/tasks/1/complete" in r.url and r.request.method == "POST" ) as result: page.get_by_role( "button", name="完了にする" ).first.click() assert result.value.status == 200 API の状態を確認する with urlopen(f"{url}/tasks") as response: tasks = json.load(response) assert tasks[0]["done"] is True print("API: done=True") ページをリロードせずに表示が変わるか確認 expect(state).to_have_text("完了", timeout=2000) print(f"PASS: PID={server.pid}, UI=完了") finally: browser.close() finally: 自分が起動したプロセスだけを終了する server.terminate() try: server.wait(timeout=5) except subprocess.TimeoutExpired: server.kill() server.wait() 実行します。 python verify.py 現在の app.py では、API の検証は成功しますが、画面表示の検証で失敗するはずです。 API: done=True AssertionError: ... Expected: "完了" Received: "未完了" つまり、API は更新されているのに、UI が更新されていないことを検出できました。 この verify.py は説明用に手書きしたスクリプトであり、pstack が自動生成したものではありません。実際のプロジェクトでは、こうした検証方法を Verification Skill に組み込み、Agent が繰り返し実行できるようにします。 Step 5：/debug で修正し、もう一度検証する ここで /debug、または /diagnosing-bugs を使って原因を調べます。 Step 3 の実装では、completeTask() が API を呼び出すだけで、画面を更新していませんでした。 async function completeTask(id) { await fetch(/tasks/${id}/complete, { method: "POST" }); } そこで、await refresh() を追加します。 async function completeTask(id) { await fetch(/tasks/${id}/complete, { method: "POST" }); await refresh(); } これでコードは修正できました。 しかし、ここでもう一つ問題があります。 Step 4 でポート 8000 に起動した Uvicorn は、まだ古いコードを読み込んだままです。 今回の起動コマンドには --reload を指定していません。 そのため、app.py を修正しても、ポート 8000 で動いているプロセスには自動的に反映されません。 仮に Agent がもう一度、同じポートで起動しようとしても、 python -m uvicorn app:app --port 8000 既存のプロセスがポートを使用しているため、起動に失敗します。 それでも localhost にアクセスすれば、古いプロセスが応答します。 ここで Agent が「まだ UI が更新されない」と判断し、正しく修正したコードを再び変更してしまう可能性があります。 以前、自分もこのような問題に遭遇しました。 そこで、Step 4 で作成した verify.py をもう一度実行します。 python verify.py このスクリプトはポート 8000 の既存プロセスを利用せず、現在のコードを新しいプロセスで起動します。 修正が正しく反映されていれば、次のような結果が期待できます。 API: done=True PASS: PID=12345, UI=完了 これで、現在のコードで起動したアプリが期待どおりに動作することを確認できます。 最後に、今回の不具合を Feature Map の検証項目に残しておきます。 タスクの完了ボタンを押したあと、ページをリロードせずに対象タスクの表示が「完了」に変わること。 あわせて、検証時には既存のプロセスを安易に再利用せず、新しく起動したアプリを対象にすることも手順に含めておきます。 必要に応じて /maintain-verification-skill で検証手順を更新し、別のセッションへ引き継ぐ場合は /handoff で作業内容を整理します。 今回の例では、API のテストが成功しただけでは UI の不具合を発見できず、コードを修正しただけでは古いプロセスの問題を回避できませんでした。 Verification Skill によって、どのアプリを起動し、何を操作し、どの結果を確認するかを決めておくことで、Agent が同じ検証ミスを繰り返す可能性を減らせます。 4. おわりに コードの実装を Agent に大きく任せる開発は、すでに現実的になっています。これからは、Agent Skills を設計し、組み合わせ、使いこなす能力も、エンジニアにとって重要になると思います。成果物のコードからは見えにくい能力ですが、同じモデルを使っていても、Agent が働く環境によって開発効率は大きく変わります。 特に参考になったのが、poteto の 「How I Shipped 2,500 PRs Last Month to Production」 という講演です。 そこで紹介されていた Trust Ladder という考え方が印象に残っています。最初は人間が細かく確認していても、Agent が自分でアプリを動かし、結果を検証できるようになれば、任せられる範囲を少しずつ広げられます。繰り返し起きるミスは、Lint や CI、Skills などの仕組みに落とし込みます。 Agent の作業が速くなるほど、人間が毎回すべてを確認することがボトルネックになります。その負担を減らすには、単に Agent を信頼するのではなく、信頼できるだけの検証環境を作ることが必要なのだと思います。 自分も、開発中に発見した失敗をその場限りの指摘で終わらせず、次回から防げる仕組みに変えていきたいと考えています。 参考資料 Matt Pocock — Skills for Real Engineers Matt Pocock — The /prototype Skill Matt Pocock Skills — GitHub pstack — GitHub pstack — create-verification-skill pstack — maintain-verification-skill Lauren Tan（@poteto）— How I Shipped 2,500 PRs Last Month to Production

Test Results: we manually tried test-first + fresh verification on synthetic URL deduplication: 3 cases red before the fix, 4/4 green after. No native skill triggering, model comparison or measured time savings. mattpocock/skills obra/superpowers #OpenSource

今日のGitHubトレンド mattpocock/skills AIエージェント向けに、実務的なエンジニアリングを実現するためのスキル集を提供しています。 複雑なプロセスに依存せず、ユーザーが制御しやすく、柔軟にカスタマイズや組み合わせができる小規模な設計を重視しています。 特定のモデルに依存せず、Claude CodeやGitHub Copilot、Gemini CLIなどのツールで利用可能です。

AIではじめるセルフQA：要求をMECEにしよう サマリー AI全盛の今、QAの方だけでなく、エンジニアもQAする時代が本格的になってきました。 ただ、AI は計画に書かれたとおりに実装します。計画に書かれていないことは実装しません。コードベースを読んで初めて見つかる要求の穴があります。ですので、この記事ではその穴を実装の前に見つける方法を紹介します。自分はこれを define-done という Agentスキルにしています。 題材のリポジトリは YasuakiOmokawa/skills で公開しています。 計画どおりに実装しても壊れる例 次の例はスキルの評価用に作った架空のものです。利用者が複数のチームに所属できるアプリで、招待を受ける処理とチームを抜ける処理は前からあります。 やりたいこと: 招待を受けたら、すぐにそのチームで作業を始められるようにしたい。 仕様駆動開発の進め方で、AI に仕様と計画を先に書かせます。 仕様: 利用者は「現在のチーム」を 1 つ持つ。現在のチームは、利用者が所属するチームのどれかでなければならない 計画: 利用者に現在のチームを新しく持たせ、招待を受けたら、そのチームを現在のチームにする 仕様と計画に食い違いはありません。AI は計画どおりに実装し、テストも書きます。テストは全部通ります。 漏れたケース: 現在のチームから抜けたとき。チームを抜ける処理は現在のチームを更新しません。現在のチームは今回新しくできたもので、この処理は前からあるからです。抜けた利用者の現在のチームは抜けたチームのまま残り、仕様の条件が破れます。 このケースは仕様にも計画にも出てこないので、テストも書かれません。チームを抜ける処理は差分にも出てこないので、レビューでも気づけません。実装の質やテストの質をいくら上げても、この穴は見つかりません。 define-done がすること: コードベースで「現在のチーム」と所属を書き換える処理をたどり、チームを抜ける処理を見つけます。そして、抜けたら現在のチームをどうするか (別の所属チームに移すか、空にするか) を、実装の前に人に問います。人が決めた答えは受け入れ基準になります。 仕様駆動開発との使い分け 仕様駆動開発 (SDD) は仕様を先に書き、実装を仕様に合わせる進め方です。仕様に書いたことは確実に実装されます。一方で、仕様に書いていないことは実装されません。仕様は、書いた人 (人でも AI でも) が思いついた範囲しか書けないからです。 define-done は既存のコードを調査して、仕様と計画に書かれていないケースを探します。仕様駆動開発の代わりではなく、仕様と計画を書いた後、実装の前に挟む工程です。 手軽に要求のMECE検査をしたいときに define-done を使うだけでも大丈夫です。 なお、筆者はSDDにはフラットな立場です。賛成も否定もしません。 穴はどこでうまれるか？ AI は計画の範囲を正しく実装します。抜けは計画の外、つまりコードベースの側にあります。同じ状態を書き換える既存の処理、変えた定義を使う別の箇所、許可された依存を全部並べるテストなどです。 この穴が生まれるのは、計画を書く人がそうした経路をすべては知らないときです。たとえば次のような人です。 大きなリポジトリや古いリポジトリを扱う人 入ったばかりのメンバーや、他チームのコードに手を入れる人 計画そのものも AI に書かせている人 3 つ目は見過ごされがちです。計画を書く AI も、コードベースを全部は読んでいないと自分は考えているからです。 4 段に分けて検証する define-done は、計画を 1 回のレビューで済ませず、4 段に分けて検証します。AI の検証の力をできるだけ引き出すために、こう設計しました。 分けるねらいは 2 つです。 1 段で見る観点を 1 つに絞る 各段の結果を計画に書き、次の段がそれを根拠にして確かめ直す。たとえば 3 段目は、2 段目が書いた受け入れ基準を仕様とコードに突き合わせ、基準の側の抜けも見つけます 抜けや矛盾が残れば、3 段目の後で止めて人に返します。冒頭の例の抜けを見つけるのも、この 3 段目です。 多段にした理由 LLM は何もないところから正しいものを作るより、出したものを根拠に照らして直すほうが得意です。偽陽性 (本当は問題でないものを問題と言うこと) を減らすにも、一度で判定させるより、段を分けて確かめさせるほうが向いています。研究でも、次のことが報告されています。 同じ LLM に、出力への指摘と書き直しを繰り返させると、7 つの課題で 1 回で出すより平均およそ 20 ポイント良くなった (Madaan et al., NeurIPS 2023) 下書きを作り、それを確かめる問いを立て、問いに別々に答えてから最終回答を書く、という 4 段の手順で、幻覚が減った (Dhuliawala et al., Findings of ACL 2024) 要約で、下書き・批評・書き直しを 1 つの指示にまとめるより、3 つの指示に分けて順に回すほうが、良い要約になった (Sun et al., Findings of ACL 2024) ただし、多段にすれば必ず良くなるわけではありません。外からの手がかり無しに LLM が自分の答えを見直すだけでは、推論の正しさは上がらず、かえって下がることがあると報告されています (Huang et al., ICLR 2024)。自己修正の研究をまとめた調査も、うまくいくのは確かな外部の手がかりがある課題だと整理しています (Kamoi et al., TACL 2024)。 define-done の各段はリポジトリのコードを根拠にし、検索やコマンドは実際に動かして確かめます。研究が「効く」とする、外の手がかりで確かめる形に合わせました。 大事なところは人が決めよう 3 段目では計画を次の順で調べます。 計画が書き換える状態と、変更する共有の定義を挙げる その状態を書き換える処理と、その定義を使う箇所を、計画が名指ししないものも含めてリポジトリの中ですべてたどる 仕様がその状態に課す条件と突き合わせる。条件にはほかの状態との関係も含む 条件を破る経路が見つかったら、その経路を名指しして、実装に進ませない 冒頭の例では、2 で「現在のチーム」を書き換える処理と、チームの所属を変える処理をたどります。その途中で、チームを抜ける処理が見つかります。3 で仕様の条件と比べると、この処理は現在のチームを更新しないので、条件を破ります。 4 で実装に進ませないのは、抜けをどう埋めるかが仕様の判断だからです。AI はここで計画を勝手に直さず、人に返します。 見つけた抜けを観測できる基準にする 抜けの埋め方を決めたら、その埋め方を受け入れ基準にします。基準は操作と、外から観測できる結果を 1 組にして書きます。 「チームを抜けた後、現在のチームは、抜けたチームでない」 「リンクは 30 分まで有効」なら、30 分の直前と直後の両方を観測する 資料が決めていない値は、推測で埋めません。たとえば仕様に再送の上限が無ければ、AI は上限を決めず、不足している情報として人に返します。 AI と人の受け持ち 抜けを見つけるのは AI で、埋め方を決めるのは人です。コードベースに明るくない人でも、この方法は使えます。抜けは根拠のファイルや行と一緒に返ってくるので、根拠をたどれば確かめられます。 ただし、あくまで決めるのは人です。 規模の限界もありますので、追いきれなかった比較を、define-done は「未検証」として返し、実装に進む許可を出しません。 grill-with-docs との併用 計画について人と詰めながら抜けを探すスキルは、Matt Pocock さんの grill-with-docs が代表的です。 違いは抜けの見つけ方です。grill-with-docs で抜けが見つかるかは、AI が問いを思いつけるかに左右されます。define-done は、計画が書き換える状態の書き手をすべてたどる、と手順で決めています。 2 つは前後に並べて使えます。 grill-with-docs で、仕様と計画の方針を人と詰める define-done で、できた計画をコードベースに照らし、抜けを洗い出して受け入れ基準にする define-done が人に返した問い (例なら「抜けたら現在のチームをどうするか」) を、grill-with-docs で詰めて決める 別に define-done を使う必要はない スキルが無くても、実装を頼む前に、次の問いを AI に投げれば同じことができます。 この計画を実装する前に、抜けを挙げてください。 1. 計画が書き換える状態と、変更する共有の定義を挙げる 2. それぞれについて、その状態を書き換える処理と、その定義を使う箇所を、 計画が名指ししないものも含めて、リポジトリの中ですべてたどる 3. 仕様がその状態に課す条件 (ほかの状態との関係を含む) と突き合わせ、 条件を破る経路を、ファイルと行を添えて挙げる 4. 資料が決めていない値は推測で埋めず、不足として挙げる 計画とコードは変更しないでください。 見つけた抜けを埋めて受け入れ基準にすれば、その基準がそのまま実装のテストの単位になり、完了を判定する単位になります。自分は実装と判定にも別のスキル (implement-plan、qa-ui、verify-plan) を使っていますが、とりあえず define-done があれば、精緻な受け入れ基準が書けますので、安心して実装できます。 エンジニアがQAできると嬉しいことが多いので、やってみることをおすすめします。 参考 題材のリポジトリ: YasuakiOmokawa/skills define-done の SKILL.md (commit 0ffa194): github.com/YasuakiOmokawa/skills/blob/0ffa194ab2a… 追跡と突き合わせの規則: github.com/YasuakiOmokawa/skills/blob/0ffa194ab2a… grill-with-docs (mattpocock/skills): github.com/mattpocock/skills/blob/main/skills/eng… Madaan, A. et al. "Self-Refine: Iterative Refinement with Self-Feedback." NeurIPS 2023: arxiv.org Dhuliawala, S. et al. "Chain-of-Verification Reduces Hallucination in Large Language Models." Findings of ACL 2024: aclanthology.org Sun, S. et al. "Prompt Chaining or Stepwise Prompt? Refinement in Text Summarization." Findings of ACL 2024: arxiv.org Huang, J. et al. "Large Language Models Cannot Self-Correct Reasoning Yet." ICLR 2024: arxiv.org Kamoi, R. et al. "When Can LLMs Actually Correct Their Own Mistakes? A Critical Survey of Self-Correction of LLMs." TACL 2024: arxiv.org

Is my Claude Code workflow overengineered? Looking for ways to reduce token usage I use Claude Code to maintain a WordPress site built with Etch and Automatic.css. I define requirements and make decisions; CC implements them. Codex acts as a separate reviewer and files findings as tickets. My setup uses two private Git repos: Project repo: code, Markdown tickets, specifications, ADRs, project-specific skills, and validation scripts. Shared Wiki repo: reusable skills, technical references, and known mistakes organized by language/tool. Skills have short core instructions and optional references. Each task goes through custom /ticket-start and /ticket-done workflows: read relevant context, implement, verify acceptance criteria, update the ticket, record reusable lessons, commit, and push. Larger changes get independent review. I also use Matt Pocock’s skills⁠, mainly TDD and code review. This helps prevent repeated mistakes, but usage feels roughly 2× higher. That isn’t a controlled comparison yet. Initial context only increased from about 81k to 84k tokens, while finishing tasks accounted for 21–51% of estimated cost in a small sample. I suspect the overhead comes from repeated reading, reviews, and updating/validating knowledge across both repos. For people using similar setups: What would you simplify first? How do you keep shared knowledge useful without loading too much context? When does a mistake deserve a permanent rule? Do you review every task independently, or only risky changes? Would you keep custom workflows or use a thinner layer around Matt’s skills? I want to keep reliable verification and reusable knowledge while reducing the cost of the process itself.

This is the most 2026 PR I've ever merged Literally fixed a bug with an adjective skills#1342

Tried this? github.com/mattpocock/skills/tree/main/skills/pro…